api-docs.yml

swagger: '2.0'
info:
  title: SEMAPHORE
  description: Semaphore API
  version: "2.2.0"

host: localhost:3000

consumes:
  - application/json
produces:
  - application/json
  - text/plain; charset=utf-8

tags:
  - name: authentication
    description: Authentication, Logout & API Tokens
  - name: project
    description: Everything related to a project
  - name: user
    description: User-related API

schemes:
  - http
  - https

basePath: /api

definitions:

  Pong:
    type: string
    x-example: pong

  Login:
    type: object
    properties:
      auth:
        type: string
        description: Username/Email address
        x-example: user@semaphore.com
      password:
        type: string
        format: password
        description: Password

  UserRequest:
    type: object
    properties:
      name:
        type: string
        x-example: Integration Test User
        example: Integration Test User
      username:
        type: string
        x-example: test-user
        example: test-user
      email:
        type: string
        x-example: test@ansiblesemaphore.test
        example: test@ansiblesemaphore.test
      alert:
        type: boolean
      admin:
        type: boolean

  UserPutRequest:
    type: object
    properties:
      name:
        type: string
        x-example: Integration Test User2
        example: Integration Test User2
      username:
        type: string
        x-example: test-user2
        example: test-user2
      email:
        type: string
        x-example: test2@ansiblesemaphore.test
        example: test2@ansiblesemaphore.test
      alert:
        type: boolean
      admin:
        type: boolean
  User:
    type: object
    properties:
      id:
        type: integer
        minimum: 1
      name:
        type: string
      username:
        type: string
      email:
        type: string
      created:
        type: string
        pattern: ^\d{4}-(?:0[0-9]{1}|1[0-2]{1})-[0-9]{2}T\d{2}:\d{2}:\d{2}Z$
      alert:
        type: boolean
      admin:
        type: boolean

  APIToken:
    type: object
    properties:
      id:
        type: string
      created:
        type: string
        pattern: ^\d{4}-(?:0[0-9]{1}|1[0-2]{1})-[0-9]{2}T\d{2}:\d{2}:\d{2}Z$
      expired:
        type: boolean
      user_id:
        type: integer
        minimum: 1

  ProjectRequest:
    type: object
    properties:
      name:
        type: string
      alert:
        type: boolean
  Project:
    type: object
    properties:
      id:
        type: integer
        minimum: 1
      name:
        type: string
      created:
        type: string
        pattern: ^\d{4}-(?:0[0-9]{1}|1[0-2]{1})-[0-9]{2}T\d{2}:\d{2}:\d{2}Z$
      alert:
        type: boolean

  AccessKeyRequest:
    type: object
    properties:
      name:
        type: string
      type:
        type: string
        enum: [ssh, aws, gcloud, do]
      project_id:
        type: integer
        minimum: 1
        x-example: 2
      key:
        type: string
      secret:
        type: string
        example: test
  AccessKey:
    type: object
    properties:
      id:
        type: integer
      name:
        type: string
      type:
        type: string
        enum: [ssh, aws, gcloud, do]
      project_id:
        type: integer
      key:
        type: string
      secret:
        type: string

  EnvironmentRequest:
    type: object
    properties:
      name:
        type: string
      project_id:
        type: integer
        minimum: 1
      password:
        type: string
      json:
        type: string
  Environment:
    type: object
    properties:
      id:
        type: integer
        minimum: 1
      name:
        type: string
      project_id:
        type: integer
        minimum: 1
      password:
        type: string
      json:
        type: string

  InventoryRequest:
      type: object
      properties:
        name:
          type: string
        project_id:
          type: integer
          minimum: 1
        inventory:
          type: string
        key_id:
          type: integer
          minimum: 1
        ssh_key_id:
          type: integer
          minimum: 1
        type:
          type: string
          enum: [static, file]
  Inventory:
    type: object
    properties:
      id:
        type: integer
      name:
        type: string
      project_id:
        type: integer
      inventory:
        type: string
      key_id:
        type: integer
      ssh_key_id:
        type: integer
      type:
        type: string
        enum: [static, file]

  RepositoryRequest:
      type: object
      properties:
        name:
          type: string
        project_id:
          type: integer
        git_url:
          type: string
        ssh_key_id:
          type: integer
  Repository:
    type: object
    properties:
      id:
        type: integer
      name:
        type: string
      project_id:
        type: integer
      git_url:
        type: string
      ssh_key_id:
        type: integer

  Task:
    type: object
    properties:
      id:
        type: integer
        example: 23
      template_id:
        type: integer
      status:
        type: string
      debug:
        type: boolean
      playbook:
        type: string
      environment:
        type: string
  TaskOutput:
    type: object
    properties:
      task_id:
        type: integer
        example: 23
      task:
        type: string
      time:
        type: string
        format: date-time
      output:
        type: string

  TemplateRequest:
    type: object
    properties:
      ssh_key_id:
        type: integer
        minimum: 1
      project_id:
        type: integer
        minimum: 1
      inventory_id:
        type: integer
        minimum: 1
      repository_id:
        type: integer
        minimum: 1
      environment_id:
        type: integer
        minimum: 1
      alias:
        type: string
      playbook:
        type: string
      arguments:
        type: string
      override_args:
        type: boolean
  Template:
    type: object
    properties:
      id:
        type: integer
        minimum: 1
      ssh_key_id:
        type: integer
        minimum: 1
      project_id:
        type: integer
        minimum: 1
      inventory_id:
        type: integer
        minimum: 1
      repository_id:
        type: integer
      environment_id:
        type: integer
        minimum: 1
      alias:
        type: string
      playbook:
        type: string
      arguments:
        type: string
      override_args:
        type: boolean

  Event:
    type: object
    properties:
      project_id:
        type: integer
      object_id:
        type:
          - integer
          - 'null'
      object_type:
        type:
          - string
          - 'null'
      description:
        type: string

  InfoType:
    type: object
    properties:
      version:
        type: string
      updateBody:
        type: string
      update:
        type: object
        properties:
          tag_name:
            type: string

securityDefinitions:
  cookie:
    type: apiKey
    name: Cookie
    in: header
  bearer:
    type: apiKey
    name: Authorization
    in: header

security:
  - bearer: []
  - cookie: []

parameters:
  project_id:
    name: project_id
    description: Project ID
    in: path
    type: integer
    required: true
    x-example: 1
  user_id:
    name: user_id
    description: User ID
    in: path
    type: integer
    required: true
    x-example: 2
  key_id:
    name: key_id
    description: key ID
    in: path
    type: integer
    required: true
    x-example: 3
  repository_id:
    name: repository_id
    description: repository ID
    in: path
    type: integer
    required: true
    x-example: 4
  inventory_id:
    name: inventory_id
    description: inventory ID
    in: path
    type: integer
    required: true
    x-example: 5
  environment_id:
    name: environment_id
    description: environment ID
    in: path
    type: integer
    required: true
    x-example: 6
  template_id:
    name: template_id
    description: template ID
    in: path
    type: integer
    required: true
    x-example: 7
  task_id:
    name: task_id
    description: task ID
    in: path
    type: integer
    required: true
    x-example: 8

paths:
  /ping:
    get:
      summary: PING test
      produces:
        - text/plain
      security: []   # No security
      responses:
        200:
          description: Successful "PONG" reply
          schema:
            $ref: "#/definitions/Pong"
          headers:
            content-type:
              type: string
              x-example: text/plain; charset=utf-8

  /ws:
    get:
      summary: Websocket handler
      schemes:
        - ws
        - wss
      responses:
        200:
          description: OK
        401:
          description: not authenticated

  /info:
    get:
      summary: Fetches information about semaphore
      description: you must be authenticated to use this
      responses:
        200:
          description: ok
          schema:
            $ref: "#/definitions/InfoType"

  /upgrade:
    get:
      summary: Check if new updates available and fetch /info
      responses:
        204:
          description: no update
        200:
          description: ok
          schema:
            $ref: "#/definitions/InfoType"
    post:
      summary: Upgrade the server
      responses:
        200:
          description: Server binary was replaced by new version, server has shut down.

  # Authentication
  /auth/login:
    post:
      tags:
        - authentication
      summary: Performs Login
      description: |
        Upon success you will be logged in
      security: []   # No security
      parameters:
        - name: Login Body
          in: body
          required: true
          schema:
            $ref: '#/definitions/Login'
      responses:
        204:
          description: You are logged in
        400:
          description: something in body is missing / is invalid

  /auth/logout:
    post:
      tags:
        - authentication
      summary: Destroys current session
      responses:
        204:
          description: Your session was successfully nuked

  # User Tokens
  /user/:
    get:
      tags:
        - user
      summary: Fetch logged in user
      responses:
        200:
          description: User
          schema:
            $ref: "#/definitions/User"

  /user/tokens:
    get:
      tags:
        - authentication
        - user
      summary: Fetch API tokens for user
      responses:
        200:
          description: API Tokens
          schema:
            type: array
            items:
              $ref: "#/definitions/APIToken"
    post:
      tags:
        - authentication
        - user
      summary: Create an API token
      responses:
        201:
          description: API Token
          schema:
            $ref: "#/definitions/APIToken"

  /user/tokens/{api_token_id}:
    parameters:
      - name: api_token_id
        in: path
        type: string
        required: true
        x-example: "kwofd61g93-yuqvex8efmhjkgnbxlo8mp1tin6spyhu="
    delete:
      tags:
        - authentication
        - user
      summary: Expires API token
      responses:
        204:
          description: Expired API Token

  # User Profiles
  /users:
    get:
      tags:
        - user
      summary: Fetches all users
      responses:
        200:
          description: Users
          schema:
            type: array
            items:
              $ref: "#/definitions/User"
    post:
      tags:
        - user
      summary: Creates a user
      consumes:
        - application/json
      parameters:
        - name: User
          in: body
          required: true
          schema:
            $ref: "#/definitions/UserRequest"
      responses:
        400:
          description: User creation failed
        201:
          description: User created
          schema:
            $ref: "#/definitions/User"

  /users/{user_id}/:
    parameters:
      - $ref: "#/parameters/user_id"
    get:
      tags:
        - user
      summary: Fetches a user profile
      responses:
        200:
          description: User profile
          schema:
            $ref: "#/definitions/User"
    put:
      tags:
        - user
      summary: Updates user details
      consumes:
        - application/json
      parameters:
        - name: User
          in: body
          required: true
          schema:
            $ref: "#/definitions/UserPutRequest"
      responses:
        204:
          description: User Updated

    delete:
      tags:
        - user
      summary: Deletes user
      responses:
        204:
          description: User deleted

  /users/{user_id}/password:
    parameters:
      - $ref: "#/parameters/user_id"
    post:
      tags:
        - user
      summary: Updates user password
      consumes:
        - application/json
      parameters:
        - name: Password
          in: body
          required: true
          schema:
            type: object
            properties:
              password:
                type: string
                format: password
      responses:
        204:
          description: Password updated

  # Projects
  /projects:
    get:
      tags:
        - projects
      summary: Get projects
      responses:
        200:
          description: List of projects
          schema:
            type: array
            items:
              $ref: "#/definitions/Project"
    post:
      tags:
        - projects
      summary: Create a new project
      consumes:
        - application/json
      parameters:
        - name: Project
          in: body
          required: true
          schema:
            $ref: '#/definitions/ProjectRequest'
      responses:
        201:
          description: Created project

  /events:
    get:
      summary: Get Events related to Semaphore and projects you are part of
      responses:
        200:
          description: Array of events in chronological order
          schema:
            type: array
            items:
              $ref: '#/definitions/Event'
  /events/last:
    get:
      summary: Get last 200 Events related to Semaphore and projects you are part of
      responses:
        200:
          description: Array of events in chronological order
          schema:
            type: array
            items:
              $ref: '#/definitions/Event'

  /project/{project_id}/:
    parameters:
      - $ref: "#/parameters/project_id"
    get:
      tags:
        - project
      summary: Fetch project
      responses:
        200:
          description: Project
          schema:
            $ref: "#/definitions/Project"
    put:
      tags:
        - project
      summary: Update project
      parameters:
        - name: Project
          in: body
          required: true
          schema:
            type: object
            properties:
              name:
                type: string
      responses:
        204:
          description: Project saved
    delete:
      tags:
        - project
      summary: Delete project
      responses:
        204:
          description: Project deleted

  /project/{project_id}/events:
    parameters:
      - $ref: '#/parameters/project_id'
    get:
      tags:
        - project
      summary: Get Events related to this project
      responses:
        200:
          description: Array of events in chronological order
          schema:
            type: array
            items:
              $ref: '#/definitions/Event'

  # User management
  /project/{project_id}/users:
    parameters:
      - $ref: "#/parameters/project_id"
    get:
      tags:
        - project
      summary: Get users linked to project
      parameters:
        - name: sort
          in: query
          required: true
          type: string
          enum: [name, username, email, admin]
          description: sorting name
          x-example: email
        - name: order
          in: query
          required: true
          type: string
          enum: [asc, desc]
          description: ordering manner
          x-example: desc
      responses:
        200:
          description: Users
          schema:
            type: array
            items:
              $ref: "#/definitions/User"
    post:
      tags:
        - project
      summary: Link user to project
      parameters:
        - name: User
          in: body
          required: true
          schema:
            type: object
            properties:
              user_id:
                type: integer
                minimum: 2
              admin:
                type: boolean
      responses:
        204:
          description: User added
  /project/{project_id}/users/{user_id}:
    parameters:
      - $ref: "#/parameters/project_id"
      - $ref: "#/parameters/user_id"
    delete:
      tags:
        - project
      summary: Removes user from project
      responses:
        204:
          description: User removed
  /project/{project_id}/users/{user_id}/admin:
    parameters:
      - $ref: "#/parameters/project_id"
      - $ref: "#/parameters/user_id"
    post:
      tags:
        - project
      summary: Makes user admin
      responses:
        204:
          description: User made administrator
    delete:
      tags:
        - project
      summary: Revoke admin privileges
      responses:
        204:
          description: User admin privileges revoked

  # project access keys
  /project/{project_id}/keys:
    parameters:
      - $ref: "#/parameters/project_id"
    get:
      tags:
        - project
      summary: Get access keys linked to project
      parameters:
          # TODO - the space in this parameter name results in a dredd warning
        - name: Key type
          in: query
          required: false
          type: string
          enum: [ssh, aws, gcloud, do]
          description: Filter by key type
          x-example: ssh
        - name: sort
          in: query
          required: true
          type: string
          enum: [name, type]
          description: sorting name
          x-example: type
        - name: order
          in: query
          required: true
          type: string
          enum: [asc, desc]
          description: ordering manner
          x-example: asc
      responses:
        200:
          description: Access Keys
          schema:
            type: array
            items:
              $ref: "#/definitions/AccessKey"
    post:
      tags:
        - project
      summary: Add access key
      parameters:
        - name: Access Key
          in: body
          required: true
          schema:
            $ref: "#/definitions/AccessKeyRequest"
      responses:
        204:
          description: Access Key created
        400:
          description: Bad type
  /project/{project_id}/keys/{key_id}:
    parameters:
      - $ref: "#/parameters/project_id"
      - $ref: "#/parameters/key_id"
    put:
      tags:
        - project
      summary: Updates access key
      parameters:
        - name: Access Key
          in: body
          required: true
          schema:
            $ref: "#/definitions/AccessKeyRequest"
      responses:
        204:
          description: Key updated
        400:
          description: Bad type
    delete:
      tags:
        - project
      summary: Removes access key
      responses:
        204:
          description: access key removed

  # project repositories
  /project/{project_id}/repositories:
    parameters:
      - $ref: "#/parameters/project_id"
    get:
      tags:
        - project
      summary: Get repositories
      parameters:
        - name: sort
          in: query
          required: true
          type: string
          enum: [name, git_url, ssh_key]
          description: sorting name
        - name: order
          in: query
          required: true
          type: string
          format: asc/desc
          enum: [asc, desc]
          description: ordering manner
      responses:
        200:
          description: repositories
          schema:
            type: array
            items:
              $ref: "#/definitions/Repository"
    post:
      tags:
        - project
      summary: Add repository
      parameters:
        - name: Repository
          in: body
          required: true
          schema:
            $ref: "#/definitions/RepositoryRequest"
      responses:
        204:
          description: Repository created
  /project/{project_id}/repositories/{repository_id}:
    parameters:
      - $ref: "#/parameters/project_id"
      - $ref: "#/parameters/repository_id"
    delete:
      tags:
        - project
      summary: Removes repository
      responses:
        204:
          description: repository removed

  # project inventory
  /project/{project_id}/inventory:
    parameters:
      - $ref: "#/parameters/project_id"
    get:
      tags:
        - project
      summary: Get inventory
      parameters:
        - name: sort
          in: query
          required: true
          type: string
          description: sorting name
          enum: [name, type]
        - name: order
          in: query
          required: true
          type: string
          description: ordering manner
          enum: [asc, desc]
      responses:
        200:
          description: inventory
          schema:
            type: array
            items:
              $ref: "#/definitions/Inventory"
    post:
      tags:
        - project
      summary: create inventory
      parameters:
        - name: Inventory
          in: body
          required: true
          schema:
            $ref: "#/definitions/InventoryRequest"
      responses:
        201:
          description: inventory created
          schema:
              $ref: "#/definitions/Inventory"
  /project/{project_id}/inventory/{inventory_id}:
    parameters:
      - $ref: "#/parameters/project_id"
      - $ref: "#/parameters/inventory_id"
    put:
      tags:
        - project
      summary: Updates inventory
      parameters:
        - name: Inventory
          in: body
          required: true
          schema:
            $ref: "#/definitions/InventoryRequest"
      responses:
        204:
          description: Inventory updated
    delete:
      tags:
        - project
      summary: Removes inventory
      responses:
        204:
          description: inventory removed

  # project environment
  /project/{project_id}/environment:
    parameters:
      - $ref: "#/parameters/project_id"
    get:
      tags:
        - project
      summary: Get environment
      parameters:
        - name: sort
          in: query
          required: true
          type: string
          format: name
          description: sorting name
          x-example: 'db-deploy'
        - name: order
          in: query
          required: true
          type: string
          format: asc/desc
          description: ordering manner
          x-example: desc
      responses:
        200:
          description: environment
          schema:
            type: array
            items:
              $ref: "#/definitions/Environment"
    post:
      tags:
        - project
      summary: Add environment
      parameters:
        - name: environment
          in: body
          required: true
          schema:
            $ref: "#/definitions/EnvironmentRequest"
      responses:
        204:
          description: Environment created
  /project/{project_id}/environment/{environment_id}:
    parameters:
      - $ref: "#/parameters/project_id"
      - $ref: "#/parameters/environment_id"
    put:
      tags:
        - project
      summary: Update environment
      parameters:
        - name: environment
          in: body
          required: true
          schema:
            $ref: "#/definitions/EnvironmentRequest"
      responses:
        204:
          description: Environment Updated
    delete:
      tags:
        - project
      summary: Removes environment
      responses:
        204:
          description: environment removed

  # project templates
  /project/{project_id}/templates:
    parameters:
      - $ref: "#/parameters/project_id"
    get:
      tags:
        - project
      summary: Get template
      parameters:
        - name: sort
          in: query
          required: true
          type: string
          description: sorting name
          enum: [alias, playbook, ssh_key, inventory, environment, repository]
        - name: order
          in: query
          required: true
          type: string
          description: ordering manner
          enum: [asc, desc]
      responses:
        200:
          description: template
          schema:
            type: array
            items:
              $ref: "#/definitions/Template"
    post:
      tags:
        - project
      summary: create template
      parameters:
        - name: template
          in: body
          required: true
          schema:
            $ref: "#/definitions/TemplateRequest"
      responses:
        201:
          description: template created
          schema:
            $ref: "#/definitions/Template"
  /project/{project_id}/templates/{template_id}:
    parameters:
      - $ref: "#/parameters/project_id"
      - $ref: "#/parameters/template_id"
    get:
      tags:
        - project
      summary: Get template
      responses:
        200:
          description: template object
          schema:
            $ref: "#/definitions/Template"
    put:
      tags:
        - project
      summary: Updates template
      parameters:
        - name: template
          in: body
          required: true
          schema:
            $ref: "#/definitions/TemplateRequest"
      responses:
        204:
          description: template updated
    delete:
      tags:
        - project
      summary: Removes template
      responses:
        204:
          description: template removed

  # tasks
  /project/{project_id}/tasks:
    parameters:
      - $ref: "#/parameters/project_id"
    get:
      tags:
        - project
      summary: Get Tasks related to current project
      responses:
        200:
          description: Array of tasks in chronological order
          schema:
            type: array
            items:
              $ref: '#/definitions/Task'
    post:
      tags:
        - project
      summary: Starts a job
      parameters:
        - name: task
          in: body
          required: true
          schema:
            type: object
            properties:
              template_id:
                type: integer
              debug:
                type: boolean
              dry_run:
                type: boolean
              playbook:
                type: string
              environment:
                type: string
      responses:
        201:
          description: Task queued
          schema:
            $ref: "#/definitions/Task"
  /project/{project_id}/tasks/last:
    parameters:
      - $ref: "#/parameters/project_id"
    get:
      tags:
        - project
      summary: Get last 200 Tasks related to current project
      responses:
        200:
          description: Array of tasks in chronological order
          schema:
            type: array
            items:
              $ref: '#/definitions/Task'
  /project/{project_id}/tasks/{task_id}:
    parameters:
      - $ref: "#/parameters/project_id"
      - $ref: "#/parameters/task_id"
    get:
      tags:
        - project
      summary: Get a single task
      responses:
        200:
          description: Task
          schema:
            $ref: "#/definitions/Task"
    delete:
      tags:
        - project
      summary: Deletes task (including output)
      responses:
        204:
          description: task deleted
  /project/{project_id}/tasks/{task_id}/output:
    parameters:
      - $ref: '#/parameters/project_id'
      - $ref: '#/parameters/task_id'
    get:
      tags:
        - project
      summary: Get task output
      responses:
        200:
          description: output
          schema:
            type: array
            items:
              $ref: "#/definitions/TaskOutput"