woodpecker/server/swagger/files/swagger.yml

swagger: "2.0"
info:
  version: 1.0.0
  title: Woodpecker 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
              }              
          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 Endpoint
  # 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: branch
          in: query
          type: string
          description: name of the branch
          required: false
        - name: number
          in: path
          type: integer
          description: sequential build number
      tags:
        - Builds
      summary: Get the latest build
      description: Returns the latest repository build.
      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 canceled 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:
    description: The user account.
    example: |
        {
          "id": 1,
          "login": "octocat",
          "email": "octocat@github.com",
          "avatar_url": "http://www.gravatar.com/avatar/7194e8d48fa1d2b689f99443b767316c",
          "admin": false,
          "active": true
        }        
    properties:
      id:
        description: The unique identifier for the account.
        type: integer
        format: int64
      login:
        description: The login name for the account.
        type: string
      email:
        description: The email address for the account.
        type: string
      avatar_url:
        description: The url for the avatar image.
        type: string
      admin:
        description: Whether the account has administrative privileges.
        type: boolean
      active:
        description: Whether the account is currently active.
        type: boolean

  Repo:
    description: A version control repository.
    example: |
        {
          "id": 1,
          "scm": "git",
          "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
        }        
    properties:
      id:
        description: The unique identifier for the repository.
        type: integer
        format: int64
      scm:
        description: |
          The source control management being used.

          Currently this is either 'git' or 'hg' (Mercurial).          
        type: string
      owner:
        description: The owner of the repository.
        type: string
      name:
        description: The name of the repository.
        type: string
      full_name:
        description: |
          The full name of the repository.

          This is created from the owner and name of the repository.          
        type: string
      avatar_url:
        description: The url for the avatar image.
        type: string
      link_url:
        description: The link to view the repository.
        type: string
      clone_url:
        description: The url used to clone the repository.
        type: string
      default_branch:
        description: The default branch of the repository.
        type: string
      private:
        description: Whether the repository is publicly visible.
        type: boolean
      trusted:
        description: |
          Whether the repository has trusted access for builds.

          If the repository is trusted then the host network can be used and
          volumes can be created.          
        type: boolean
      timeout:
        description: The amount of time in minutes before the build is killed.
        type: integer
        x-dart-type: Duration
      allow_pr:
        description: Whether pull requests should trigger a build.
        type: boolean

  Build:
    description: A build for a repository.
    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:
        description: |
          The build number.

          This number is specified within the context of the repository the build
          belongs to and is unique within that.          
        type: integer
      status:
        description: The current status of the build.
        $ref: '#definitions/BuildStatus'
      created_at:
        description: When the build request was received.
        type: integer
        format: int64
        x-dart-type: DateTime
      enqueued_at:
        description: When the build was enqueued.
        type: integer
        format: int64
        x-dart-type: DateTime
      started_at:
        description: When the build began execution.
        type: integer
        format: int64
        x-dart-type: DateTime
      finished_at:
        description: When the build was finished.
        type: integer
        format: int64
        x-dart-type: DateTime
      deploy_to:
        description: Where the deployment should go.
        type: string
      commit:
        description: The commit for the build.
        type: string
      branch:
        description: The branch the commit was pushed to.
        type: string
      message:
        description: The commit message.
        type: string
      timestamp:
        description: When the commit was created.
        type: integer
        format: int64
        x-dart-format: DateTime
      ref:
        description: The alias for the commit.
        type: string
      refspec:
        description: The mapping from the local repository to a branch in the remote.
        type: string
      remote:
        description: The remote repository.
        type: string
      author:
        description: The login for the author of the commit.
        type: string
      author_avatar:
        description: The avatar for the author of the commit.
        type: string
      author_email:
        description: The email for the author of the commit.
        type: string
      link_url:
        description: |
          The link to view the repository.

          This link will point to the repository state associated with the
          build's commit.          
        type: string
      jobs:
        description: |
          The jobs associated with this build.

          A build will have multiple jobs if a matrix build was used or if a
          rebuild was requested.          
        type: array
        items:
          $ref: "#/definitions/Job"

  BuildStatus:
    description: The status of a build.
    type: string
    enum:
      - success
      - failure
      - pending
      - started
      - error
      - killed
    x-enum-descriptions:
      - The build was successful.
      - The build failed.
      - The build is pending execution.
      - The build was started.
      - There was an error running the build.
      - The build was killed either manually or through a timeout.

  Job:
    description: A single job being executed as part of a build.
    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:
        description: The unique identifier for the build.
        type: integer
        format: int64
      number:
        description: |
          The job number.

          This number is specified within the context of the build the job
          belongs to and is unique within that.          
        type: integer
      status:
        description: The current status of the job.
        $ref: '#definitions/BuildStatus'
      exit_code:
        description: The exit code for the build.
        type: integer
      enqueued_at:
        description: When the job was enqueued.
        type: integer
        format: int64
        x-dart-type: DateTime
      started_at:
        description: When the job began execution.
        type: integer
        format: int64
        x-dart-type: DateTime
      finished_at:
        description: When the job finished execution.
        type: integer
        format: int64
        x-dart-type: DateTime
      environment:
        description: |
          The environment that the job was run with.

          This is a map containing any values for matrix builds.          
        type: object

  Feed:
    description: |
      A feed entry for a build.

      Feed entries can be used to display information on the latest builds.      
    example: |
        {
          "owner": "octocat",
          "name": "hello-world",
          "full_name": "octocat/hello-world",
          "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",
        }        
    properties:
      owner:
        description: The owner of the repository.
        type: string
      name:
        description: The name of the repository.
        type: string
      full_name:
        description: |
          The full name of the repository.

          This is created from the owner and name of the repository.          
        type: string
      number:
        description: |
          The build number.

          This number is specified within the context of the repository the build
          belongs to and is unique within that.          
        type: integer
      status:
        description: The current status of the build.
        $ref: '#definitions/BuildStatus'
      created_at:
        description: When the build request was received.
        type: integer
        format: int64
        x-dart-type: DateTime
      enqueued_at:
        description: When the build was enqueued.
        type: integer
        format: int64
        x-dart-type: DateTime
      started_at:
        description: When the build began execution.
        type: integer
        format: int64
        x-dart-type: DateTime
      finished_at:
        description: When the build was finished.
        type: integer
        format: int64
        x-dart-type: DateTime
      commit:
        description: The commit for the build.
        type: string
      branch:
        description: The branch the commit was pushed to.
        type: string
      message:
        description: The commit message.
        type: string
      timestamp:
        description: When the commit was created.
        type: integer
        format: int64
        x-dart-format: DateTime
      ref:
        description: The alias for the commit.
        type: string
      refspec:
        description: The mapping from the local repository to a branch in the remote.
        type: string
      remote:
        description: The remote repository.
        type: string
      author:
        description: The login for the author of the commit.
        type: string
      author_avatar:
        description: The avatar for the author of the commit.
        type: string
      author_email:
        description: The email for the author of the commit.
        type: string
      link_url:
        description: |
          The link to view the repository.

          This link will point to the repository state associated with the
          build's commit.          
        type: string