path: root/docs/api.yaml

swagger: '2.0'
info:
  title: Patchwork API
  description: |
    Patchwork is a web-based patch tracking system designed to facilitate the
    contribution and management of contributions to an open-source project.
  version: "1.0"
host: patchwork.ozlabs.org
schemes:
  - http
  - https
securityDefinitions:
  basicAuth:
    type: basic
    description: HTTP Basic Authentication. Works over `HTTP` and `HTTPS`
basePath: /api/1.0
produces:
  - application/json
paths:
  /:
    get:
      summary: API metadata.
      description: |
        The Metadata endpoint returns information about the API itself.
        The response includes the version of the API.
      responses:
        200:
          description: An API metadata object.
          schema:
            $ref: '#/definitions/Metadata'
        default:
          description: Unexpected error.
          schema:
            $ref: '#/definitions/Error'
  /projects:
    get:
      summary: List available projects.
      description: |
        Returns information about all projects available on this patchwork
        instance.
      parameters:
        - $ref: '#/parameters/perPageParam'
        - $ref: '#/parameters/pageParam'
      tags:
        - Projects
      responses:
        200:
          description: An array of projects objects.
          schema:
            type: array
            items:
              $ref: '#/definitions/Project'
        default:
          description: Unexpected error.
          schema:
            $ref: '#/definitions/Error'
  /projects/{projectId}:
    get:
      summary: Retrieve a project.
      description: |
        Returns information about a single project available on this patchwork
        instance.
      parameters:
        - $ref: '#/parameters/projectId'
      tags:
        - Projects
      responses:
        200:
          description: A project object.
          schema:
            $ref: '#/definitions/Project'
        404:
          description: The project does not exist
        default:
          description: Unexpected error.
          schema:
            $ref: '#/definitions/Error'
    patch:
      summary: Update a project.
      description: |
        Update information about a single project available on this patchwork
        instance.
      parameters:
        - $ref: '#/parameters/projectId'
      tags:
        - Projects
      security:
       - basicAuth: []
      responses:
        200:
          description: A project object.
          schema:
            $ref: '#/definitions/Project'
        403:
          description: The user is not authenticated or is not a superuser.
        404:
          description: The project does not exist.
        default:
          description: Unexpected error.
          schema:
            $ref: '#/definitions/Error'
  /people:
    get:
      summary: List available people.
      description: |
        Returns information about all people who have submitted patches on this
        patchwork instance.
      parameters:
        - $ref: '#/parameters/perPageParam'
        - $ref: '#/parameters/pageParam'
      tags:
        - People
      responses:
        200:
          description: An array of people objects.
          schema:
            type: array
            items:
              $ref: '#/definitions/People'
        403:
          description: The user is not authenticated.
        default:
          description: Unexpected error.
          schema:
            $ref: '#/definitions/Error'
  /people/{personId}:
    get:
      summary: Retrieve a person.
      description: |
        Returns information about a single person who has submitted patches on
        this patchwork instance.
      parameters:
        - $ref: '#/parameters/personId'
      tags:
        - People
      responses:
        200:
          description: A person object.
          schema:
            $ref: '#/definitions/People'
        403:
          description: The user is not authenticated.
        404:
          description: The person does not exist.
        default:
          description: Unexpected error.
          schema:
            $ref: '#/definitions/Error'
  /users:
    get:
      summary: List available users.
      description: |
        Returns information about all users registerd on this Patchwork
        instance.
      parameters:
        - $ref: '#/parameters/perPageParam'
        - $ref: '#/parameters/pageParam'
      tags:
        - Users
      security:
       - basicAuth: []
      responses:
        200:
          description: An array of user objects.
          schema:
            type: array
            items:
              $ref: '#/definitions/User'
        default:
          description: Unexpected error.
          schema:
            $ref: '#/definitions/Error'
  /users/{userId}:
    get:
      summary: Retrieve a user.
      description: |
        Returns information about a single user registerd on this Patchwork
        instance.
      parameters:
        - $ref: '#/parameters/userId'
      tags:
        - Users
      security:
       - basicAuth: []
      responses:
        200:
          description: A user object.
          schema:
            $ref: '#/definitions/User'
        403:
          description: The user is not authenticated.
        404:
          description: The user does not exists.
        default:
          description: Unexpected error.
          schema:
            $ref: '#/definitions/User'
  /patches:
    get:
      summary: List available patches
      description: |
        Returns information about all patches available on this patchwork
        instance.
      parameters:
        - $ref: '#/parameters/perPageParam'
        - $ref: '#/parameters/pageParam'
        - $ref: '#/parameters/sinceParam'
        - $ref: '#/parameters/untilParam'
      tags:
        - Patches
      responses:
        200:
          description: An array of patch objects.
          schema:
            type: array
            items:
              $ref: '#/definitions/Patch'
        default:
          description: Unexpected error.
          schema:
            $ref: '#/definitions/Error'
  /patches/{patchId}:
    get:
      summary: Retrieve a patch.
      description: |
        Returns information about a single patch available on this patchwork
        instance.
      parameters:
        - $ref: '#/parameters/patchId'
      tags:
        - Patches
      responses:
        200:
          description: A patch object.
          schema:
            $ref: '#/definitions/PatchDetail'
        404:
          description: The patch does not exist
        default:
          description: Unexpected error.
          schema:
            $ref: '#/definitions/Error'
    patch:
      summary: Update a patch.
      description: |
        Update information about a patch.
      parameters:
        - $ref: '#/parameters/patchId'
      tags:
        - Patches
      security:
       - basicAuth: []
      responses:
        200:
          description: A patch object.
          schema:
            $ref: '#/definitions/PatchDetail'
        403:
          description: |
            The user is not authenticated, or the user did not create the
            patch and is not a super user.
        404:
          description: The patch does not exist
        default:
          description: Unexpected error.
          schema:
            $ref: '#/definitions/Error'
  /patches/{patchId}/checks:
    get:
      summary: List checks for given patch.
      description: |
        Checks store the results of any tests executed (or executing) for a
        given patch. This is useful, for example, when using a continuous
        integration (CI) system to test patches.
      parameters:
        - $ref: '#/parameters/patchId'
        - $ref: '#/parameters/perPageParam'
        - $ref: '#/parameters/pageParam'
      tags:
        - Checks
      responses:
        200:
          description: A check object.
          schema:
            $ref: '#/definitions/Check'
        404:
          description: The parent patch does not exist
        default:
          description: Unexpected error.
          schema:
            $ref: '#/definitions/Error'
  # TODO(stephenfin): Document creation of checks, listing of users
parameters:
  # ID Parameters
  projectId:
    name: projectId
    description: ID of project that needs to be retrieved.
    in: path
    type: integer
    format: int32
    required: true
  personId:
    name: personId
    description: ID of person that needs to be retrieved.
    in: path
    type: integer
    format: int32
    required: true
  userId:
    name: userId
    description: ID of a user.
    in: path
    type: integer
    format: int32
    required: true
  patchId:
    name: patchId
    description: |
      ID of patch that needs to be retrieved. This should be one of: a patch
      ID, a patch hash, a Message-ID.
    in: path
    type: string
    required: true
  # Generic parameters
  pageParam:
    name: page
    description: page to retrieve
    in: query
    type: integer
    format: int32
    minimum: 1
    default: 1
  perPageParam:
    name: per_page
    description: custom page size
    in: query
    type: integer
    format: int32
    minimum: 0
    maximum: 100
    default: 30
  sinceParam:
    name: since
    description: only items modified after this date will be returned
    in: query
    type: string
    format: date
  untilParam:
    name: until
    description: only items modified before this date will be returned
    in: query
    type: string
    format: date
definitions:
  Metadata:
    properties:
      revision:
        type: integer
        description: Revision of the API.
  Project:
    properties:
      id:
        type: integer
        description: Unique identifier of project.
      url:
        type: string
        description: url to project.
      name:
        type: string
        description: Name of project.
      link_name:
        type: string
        description: Link name of project.
      list_id:
        type: string
        description: Mailing list identifier for project.
      subject_match:
        type: string
        description: Regex used for email filtering.
      list_email:
        type: string
        description: Mailing list email address for project.
      web_url:
        type: string
        description: Upstream website URL for project.
      scm_url:
        type: string
        description: SCM clone URL for project.
      webscm_url:
        type: string
        description: SCM web interface URL for project.
  Patch:
    properties:
      id:
        type: integer
        description: Unique identifier of patch.
      url:
        type: string
        description: URL to patch.
      project:
        type: string
        description: URL to patch's project.
      msgid:
        type: string
        description: Message ID header from patch mail.
      date:
        type: string
        format: date-time
        description: Submission date of patch.
      name:
        type: string
        description: Name of patch.
      commit_ref:
        type: string
        description: Ref of committed patch.
      pull_url:
        type: string
        description: URL to patch pull request.
      state:
        type: string
        description: The state of the patch.
      archived:
        type: boolean
        description: Archival state of patch.
      hash:
        type: string
        description: Hash of patch's diff.
      submitter:
        type: string
        description: URL for submitter of patch.
      delegate:
        type: integer
        description: URL for delegate assigned to patch.
      mbox:
        type: string
        description: Link to the raw patch mbox contents.
      check:
        type: string
        description: The combined check status for the patch.
        enum:
          - pending
          - success
          - warning
          - fail
      checks:
        type: string
        description: URL to patch's checks endpoint.
      tags:
        type: array
        description: Tags associated with patch.
        items:
          type: string
  PatchDetail:
    allOf:
      - $ref: '#/definitions/Patch'
    properties:
      diff:
        type: string
        description: Diff of patch.
      content:
        type: string
        description: Message of patch.
      headers:
        type: array
        description: The headers of the patch.
        items:
          type: string
  People:
    properties:
      id:
        type: integer
        description: Unique identifier of person.
      url:
        type: string
        description: URL to person.
      name:
        type: string
        description: Name of person.
      email:
        type: string
        description: Email of person.
      user:
        type: string
        description: URL for user connected to person.
  Check:
    properties:
      id:
        type: integer
        description: Unique identifier of check.
      url:
        type: string
        description: URL to check.
      user:
        type: string
        description: URL for creator of check.
      date:
        type: string
        format: date-time
      state:
        type: string
        description: The state of the check.
        enum:
          - pending
          - success
          - warning
          - fail
      target_url:
        type: string
        description: The target URL associated with this check.
      context:
        type: string
        description: |
          A label to discern check from checks of other testing systems.
      description:
        type: string
        description: A brief description of the check.
  User:
    properties:
      id:
        type: integer
        description: Unique identifier of user.
      url:
        type: string
        description: URL to user.
      username:
        type: string
        description: Username of user.
      first_name:
        type: string
        description: First name of user.
      last_name:
        type: string
        description: Last name of user.
      email:
        type: string
        description: Email of user.
  Error:
    properties:
      code:
        type: integer
        format: int32
      message:
        type: string
      fields:
        type: string