woodpecker/docs/swagger.yml

swagger: "2.0"
info:
  version: 1.0.0
  title: Drone API
  license:
    name: Creative Commons 4.0 International
    url: "http://creativecommons.org/licenses/by/4.0/"

host: "localhost:8080"
basePath: /api
schemes:
  - http
  - https
consumes:
  - application/json
produces:
  - application/json

#
# Operation tags
#

tags:
  - name: Repos
  - name: Builds
  - name: User
  - name: Users

#
# Security Definitions
#

security:
  - accessToken: []
securityDefinitions:
  accessToken:
    type: apiKey
    in: query
    name: access_token

#
# Endpoint Definitions
#

paths:

  #
  # Repos Endpoint
  #

  /repos/{owner}/{name}:
    get:
      parameters:
        - name: owner
          in: path
          type: string
          description: owner of the repository
        - name: name
          in: path
          type: string
          description: name of the repository
      tags:
        - Repos
      summary: Get a repo
      description: Retrieves the details of a repository.
      security:
        - accessToken: []
      responses:
        200:
          schema:
            $ref: "#/definitions/Repo"
        404:
          description: |
            Unable to find the repository.

    patch:
      parameters:
        - name: owner
          in: path
          type: string
          description: owner of the repository
        - name: name
          in: path
          type: string
          description: name of the repository
        - name: repo
          in: body
          description: The updated repository JSON
          schema:
            $ref: '#/definitions/Repo'
            example: |
              {
                "timeout": 60,
                "private": false,
                "trusted": false,
                "allow_pr": true,
                "allow_push": true,
                "allow_deploys": false,
                "allow_tags": false
              }
          required: true
      tags:
        - Repos
      summary: Updates a repo
      description: Updates the specified repository.
      security:
        - accessToken: []
      responses:
        200:
          schema:
            $ref: "#/definitions/Repo"
        400:
          description: |
            Unable to update the repository in the database.
        404:
          description: |
            Unable to find the repository.

    post:
      parameters:
        - name: owner
          in: path
          type: string
          description: owner of the repository
        - name: name
          in: path
          type: string
          description: name of the repository
      tags:
        - Repos
      summary: Activates a repo
      description: Activates a repository.
      security:
        - accessToken: []
      responses:
        200:
          schema:
            $ref: "#/definitions/Repo"
        400:
          description: |
            Unable to update the Repository record in the database
        403:
          description: |
            Unable to activate the Repository due to insufficient privileges
        404:
          description: |
            Unable to retrieve the Repository from the remote system (ie GitHub)
        409:
          description: |
            Unable to activate the Repository because it is already activate
        500:
          description: |
            Unable to activate the Repository due to an internal server error. This may indicate a problem adding hooks to the remote system (ie Github), generating SSH deployment keys, or persisting to the database.

    delete:
      parameters:
        - name: owner
          in: path
          type: string
          description: owner of the repository
        - name: name
          in: path
          type: string
          description: name of the repository
      tags:
        - Repos
      summary: Delete a repo
      description: Permanently deletes a repository. It cannot be undone.
      security:
        - accessToken: []
      responses:
        200:
          description: |
            Successfully deleted the Repository
        400:
          description: |
            Unable to remove post-commit hooks from the remote system (ie GitHub)
        404:
          description: |
            Unable to find the Repository in the database
        500:
          description: |
            Unable to update the Repository record in the database


  #
  # Repos Param Encryption Enpoint
  # TODO: properly add the input output schema

  /repos/{owner}/{name}/encrypt:
    post:
      parameters:
        - name: owner
          in: path
          type: string
          description: owner of the repository
        - name: name
          in: path
          type: string
          description: name of the repository
      tags:
        - Repos
      summary: Encrypt repo secrets
      description: Encryptes a Yaml file with secret environment variables for secure public storage.
      security:
        - accessToken: []
      responses:
        200:
          description: The encrypted parameters.
        400:
          description: |
            Unable to encrypt the parameters.
        404:
          description: |
            Unable to find the repository.


  #
  # Builds Endpoint
  #

  /repos/{owner}/{name}/builds:
    get:
      parameters:
        - name: owner
          in: path
          type: string
          description: owner of the repository
        - name: name
          in: path
          type: string
          description: name of the repository
      tags:
        - Builds
      summary: Get recent builds
      description: Returns recent builds for the repository based on name.
      security:
        - accessToken: []
      responses:
        200:
          description: The recent builds.
          schema:
            type: array
            items:
              $ref: "#/definitions/Build"
        404:
          description: |
            Unable to find the Repository in the database

  /repos/{owner}/{name}/builds/{number}:
    get:
      parameters:
        - name: owner
          in: path
          type: string
          description: owner of the repository
        - name: name
          in: path
          type: string
          description: name of the repository
        - name: number
          in: path
          type: integer
          description: sequential build number
      tags:
        - Builds
      summary: Get a build
      description: Returns the repository build by number.
      security:
        - accessToken: []
      responses:
        200:
          description: The build.
          schema:
            $ref: "#/definitions/Build"
        404:
          description: |
            Unable to find the Repository or Build

    post:
      parameters:
        - name: owner
          in: path
          type: string
          description: owner of the repository
        - name: name
          in: path
          type: string
          description: name of the repository
        - name: number
          in: path
          type: integer
          description: sequential build number
      tags:
        - Builds
      summary: Restart a build
      description: Restart the a build by number.
      security:
        - accessToken: []
      responses:
        200:
          description: Successfully restarted the Build.
          schema:
            $ref: "#/definitions/Build"
        404:
          description: |
            Unable to find the Repository or Build.
        409:
          description: |
            Cannot re-start a Build that is running.


  #
  # Jobs Endpoint
  #

  /repos/{owner}/{name}/logs/{number}/{job}:
    get:
      parameters:
        - name: owner
          in: path
          type: string
          description: owner of the repository
        - name: name
          in: path
          type: string
          description: name of the repository
        - name: number
          in: path
          type: integer
          description: sequential build number
        - name: job
          in: path
          type: integer
          description: sequential job number
      tags:
        - Builds
      summary: Get build logs
      description: Returns the build logs for a specific job (build step).
      produces:
        - text/plain
      security:
        - accessToken: []
      responses:
        200:
          description: The logs for the requested job.
        404:
          description: |
            Unable to find the repository, build or job.

    delete:
      parameters:
        - name: owner
          in: path
          type: string
          description: owner of the repository
        - name: name
          in: path
          type: string
          description: name of the repository
        - name: number
          in: path
          type: integer
          description: sequential build number
        - name: job
          in: path
          type: integer
          description: sequential job number
      tags:
        - Builds
      summary: Cancel a Job
      description: Cancel the a build job by number.
      security:
        - accessToken: []
      responses:
        200:
          description: Successfully cancelled the Job
        404:
          description: |
            Unable to find the Repository or Job
        409:
          description: |
            Cannot cancel a Job that is already stopped


  #
  # User Endpoint
  #

  /user:
    get:
      summary: Gets a user
      description: Returns the currently authenticated user.
      security:
        - accessToken: []
      tags:
        - User
      responses:
        200:
          description: The currently authenticated user.
          schema:
            $ref: "#/definitions/User"
    patch:
      summary: Updates a user
      description: Updates the currently authenticated user.
      tags:
        - User
      parameters:
        - name: user
          in: body
          description: Updates to the user.
          required: true
          schema:
            $ref: "#/definitions/User"
      responses:
        200:
          description: The updated user.
          schema:
            $ref: "#/definitions/User"
        400:
          description: |
            Unable to update the user in the database


  #
  # User Repos
  #

  /user/repos:
    get:
      summary: Get user repos
      description: |
        Retrieve the currently authenticated User's Repository list
      tags:
        - User
      responses:
        200:
          schema:
            type: array
            items:
              $ref: "#/definitions/Repo"
        400:
          description: |
            Unable to retrieve Repository list


  #
  # Users Endpoint
  #

  /users:
    get:
      tags:
        - Users
      summary: Get all users
      description: Returns all registered, active users in the system.
      security:
        - accessToken: []
      responses:
        200:
          description: All registered users.
          schema:
            type: array
            items:
              $ref: "#/definitions/User"

  /users/{login}:
    get:
      parameters:
        - name: login
          in: path
          type: string
          description: user login
      tags:
        - Users
      summary: Get a user
      description: Returns a user with the specified login name.
      security:
        - accessToken: []
      responses:
        200:
          description: Returns the user.
          schema:
            $ref: "#/definitions/User"
        404:
          description: Cannot find user with matching login.

    post:
      parameters:
        - name: login
          in: path
          type: string
          description: user login to activate
      tags:
        - Users
      summary: Create a user
      description: Creates a new user account with the specified external login.
      security:
        - accessToken: []
      responses:
        201:
          description: Returns the created user.
          schema:
            $ref: "#/definitions/User"
        400:
          description: |
            Error inserting User into the database

    patch:
      parameters:
        - name: login
          in: path
          type: string
          description: user login
        - name: user
          in: body
          description: changes to the user
          schema:
            $ref: '#/definitions/User'
            example: |
                {
                  "email": "octocat@github.com",
                  "admin": false,
                  "active": true
                }
          required: true

      tags:
        - Users
      summary: Update a user
      description: Updates an existing user account.
      security:
        - accessToken: []
      responses:
        200:
          description: Returns the updated user.
          schema:
            $ref: "#/definitions/User"
        400:
          description: |
            Error updating the User in the database

    delete:
      parameters:
        - name: login
          in: path
          type: string
          description: user login
      tags:
        - Users
      summary: Delete a user
      description: Deletes the user with the specified login name.
      security:
        - accessToken: []
      responses:
        204:
          description: |
            Successfully deleted the User
        400:
          description: |
            Error deleting the User from the database
        403:
          description: |
            Cannot delete your own User account
        404:
          description: |
            Cannot find the User

#
# Schema Definitions
#

definitions:
  User:
    example: |
        {
          "id": 1,
          "login": "octocat",
          "email": "octocat@github.com",
          "avatar_url": "http://www.gravatar.com/avatar/7194e8d48fa1d2b689f99443b767316c",
          "admin": false,
          "active": true
        }
    properties:
      id:
        type: integer
        format: int64
      login:
        type: string
      email:
        type: string
      avatar_url:
        type: string
      admin:
        type: boolean
      active:
        type: boolean


  Repo:
    example: |
        {
          "id": 1,
          "owner": "octocat",
          "name": "hello-world",
          "full_name": "octocat/hello-world",
          "avatar_url": "https://avatars.githubusercontent.com/u/2181346?v=3",
          "link_url": "https://github.com/octocat/hello-world",
          "clone_url": "https://github.com/octocat/hello-world.git",
          "default_branch": "master",
          "timeout": 60,
          "private": false,
          "trusted": false,
          "allow_pr": true,
          "allow_push": true,
          "allow_deploys": false,
          "allow_tags": false
        }
    properties:
      id:
        type: integer
        format: int64
      owner:
        type: string
      name:
        type: string
      full_name:
        type: string
      avatar_url:
        type: string
      link_url:
        type: string
      clone_url:
        type: string
      default_branch:
        type: string
      private:
        type: boolean
      trusted:
        type: boolean
      timeout:
        type: integer
      allow_pr:
        type: boolean
      allow_push:
        type: boolean
      allow_deploys:
        type: boolean
      allow_tags:
        type: boolean


  Build:
    example: |
        {
          "id": 1,
          "number": 1,
          "event": "push",
          "status": "success",
          "created_at": 1443677151,
          "enqueued_at": 1443677151,
          "started_at": 1443677151,
          "finished_at": 1443677255,
          "commit": "2deb7e0d0cbac357eeb110c8a2f2f32ce037e0d5",
          "branch": "master",
          "ref": "refs/heads/master",
          "remote": "https://github.com/octocat/hello-world.git",
          "message": "New line at end of file. --Signed off by Spaceghost",
          "timestamp": 1443677255,
          "author": "Spaceghost",
          "author_avatar": "https://avatars0.githubusercontent.com/u/251370?v=3",
          "author_email": "octocat@github.com",
          "link_url": "https://github.com/octocat/hello-world/commit/762941318ee16e59dabbacb1b4049eec22f0d303",
          "jobs": [
            {
              "id": 1,
              "number": 1,
              "status": "success",
              "enqueued_at": 1443677151,
              "started_at": 1443677151,
              "finished_at": 1443677255,
              "exit_code": 0,
              "environment": { "GO_VERSION": "1.4" }
            },
            {
              "id": 2,
              "number": 2,
              "status": "success",
              "enqueued_at": 1443677151,
              "started_at": 1443677151,
              "finished_at": 1443677255,
              "exit_code": 0,
              "environment": { "GO_VERSION": "1.5" }
            }
          ]
        }
    properties:
      id:
        type: integer
        format: int64
      number:
        type: integer
      status:
        type: string
        enum:
          - success
          - failure
          - pending
          - started
          - error
          - killed
      created_at:
        type: integer
        format: int64
      enqueued_at:
        type: integer
        format: int64
      started_at:
        type: integer
        format: int64
      finished_at:
        type: integer
        format: int64
      commit:
        type: string
      branch:
        type: string
      message:
        type: string
      timestamp:
        type: integer
        format: int64
      ref:
        type: string
      refspec:
        type: string
      remote:
        type: string
      author:
        type: string
      author_avatar:
        type: string
      author_email:
        type: string
      link_url:
        type: string


  Job:
    example: |
        {
          "id": 1,
          "number": 1,
          "status": "success",
          "enqueued_at": 1443677151,
          "started_at": 1443677151,
          "finished_at": 1443677255,
          "exit_code": 0,
          "environment": { "GO_VERSION": "1.4" }
        }
    properties:
      id:
        type: integer
        format: int64
      number:
        type: integer
      status:
        type: string
        enum:
          - success
          - failure
          - pending
          - started
          - error
          - killed
      exit_code:
        type: integer
      enqueued_at:
        type: integer
        format: int64
      started_at:
        type: integer
        format: int64
      finished_at:
        type: integer
        format: int64
      environment:
        type: object