Athenian Pagination API

openapi: 3.2.0
info:
  contact:
    email: admin@athenian.co
    name: the administrator by email
  description: 'Server version: {{ server_version }} built on {{ build_date }} @ {{ commit }}


    Origin GitHub repository: athenianco/api-spec.'
  license:
    name: CC-BY-4.0
  title: '{{ title }} Pagination API'
  version: 2.1.86
servers:
- description: '{{ server_description }} - {{ server_url }}'
  url: '{{ server_url }}/v1'
tags:
- name: pagination
paths:
  /paginate/pull_requests:
    post:
      operationId: paginate_prs
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaginatePullRequestsRequest'
        x-body-name: body
      responses:
        200:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PullRequestPaginationPlan'
          description: Identifier of the created repository set.
        400:
          $ref: '#/components/responses/InvalidRequestErrorResponse'
        403:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Calling user is not allowed to access the specified repositories.
        404:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: The specified account does not exist or the user is not a member.
        422:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NoSourceDataError'
          description: The account's installation has not finished yet.
        424:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MissingSettingsError'
          description: One or more logical repositories miss the release settings.
      security:
      - bearerAuth: []
      - apiKeyAuth: []
      summary: Compute the balanced pagination plan for `/filter/pull_requests`
      tags:
      - pagination
      x-codegen-request-body-name: body
      x-openapi-router-controller: athenian.api.controllers.pagination_controller
components:
  schemas:
    PaginatePullRequestsRequest:
      additionalProperties: false
      description: 'Request of `/paginate/pull_requests`. According to the target batch size,

        compute the optimal PR updated timestamp ranges. `request` should match

        the body to be sent to `/filter/pull_requests`. `updated_from` and `updated_to`

        inside `request` are ignored.'
      example:
        request:
          account: 1
          date_from: 2020-01-23
          date_to: 2020-05-23
          exclude_inactive: true
          in:
          - '{1}'
          - github.com/athenianco/athenian-webapp
          stages:
          - wip
          with:
            author:
            - github.com/vmarkovtsev
        batch: 100
      properties:
        batch:
          description: Target batch size. The returned ranges do not guarantee the exact match.
          minimum: 1
          type: integer
        request:
          $ref: '#/components/schemas/FilterPullRequestsRequest'
      required:
      - batch
      - request
      type: object
    JIRAStatusCategory:
      description: The category of a JIRA issue status.
      enum:
      - To Do
      - In Progress
      - Done
      - No Category
      type: string
    PullRequestWith:
      additionalProperties: false
      description: 'Triage PRs by various developer participation. The aggregation is `OR` between

        the participation groups and `OR` within each group. For example, if our request is

        ```

        {"author": ["github.com/vmarkovtsev"], "reviewer": ["github.com/gkwillie", "github.com/mcuadros"]}

        ```

        then the matched PRs will have **@vmarkovtsev** as the author or either

        **@gkwillie** or **@mcuadros** as the reviewers.

        It is possible to mention whole teams using the syntax `{id}` where `id` is a team identifier (see `/teams`).'
      example:
        author:
        - github.com/vmarkovtsev
      properties:
        author:
          $ref: '#/components/schemas/DeveloperSet'
        reviewer:
          $ref: '#/components/schemas/DeveloperSet'
        commit_author:
          $ref: '#/components/schemas/DeveloperSet'
        commit_committer:
          $ref: '#/components/schemas/DeveloperSet'
        commenter:
          $ref: '#/components/schemas/DeveloperSet'
        merger:
          $ref: '#/components/schemas/DeveloperSet'
        releaser:
          $ref: '#/components/schemas/DeveloperSet'
      type: object
    RepositoryID:
      description: 'Repository name which uniquely identifies any repository in any service provider.

        The format matches the repository URL without the protocol part. No ".git" should be appended.

        We support a special syntax for repository sets: "{reposet id}" adds all the repositories

        from the given set.

        '
      example: github.com/athenianco/athenian-webapp
      type: string
    JIRAFilter:
      additionalProperties: false
      description: 'Filters related to JIRA traits. The aggregation between each filter type is *AND*.

        '
      example:
        epics:
        - DEV-167
        - DEV-230
        labels_include:
        - api,performance
        - metadata
        labels_exclude:
        - feature
        issue_types:
        - Bug
        - Task
        priorities:
        - high
        - low
        projects:
        - DEV
        - ENG
        status_categories:
        - In Progress
      properties:
        epics:
          description: JIRA issues must be included in the epics from the list.
          items:
            type: string
          type: array
        labels_include:
          description: 'Only issues having at least one label from the list will be included

            Several labels may be concatenated by a comma `,` so that all of them

            are required.

            '
          items:
            type: string
          type: array
        labels_exclude:
          description: Issues having one label from the list will be excluded.
          items:
            type: string
          type: array
        issue_types:
          description: 'Issues must have one of the given types, e.g. Bug, Task, Design Document, etc.

            '
          items:
            type: string
          type: array
        priorities:
          description: Issues must have a priority from the given list.
          items:
            type: string
          type: array
        projects:
          description: Issues must be contained in a project in the given project keys list.
          items:
            type: string
          type: array
        status_categories:
          description: The JIRA issues must have a status belonging to one of these categories.
          items:
            $ref: '#/components/schemas/JIRAStatusCategory'
          type: array
        unmapped:
          description: Select PRs that are not mapped to any JIRA issue. May not be specified with anything else.
          type: boolean
      type: object
    MissingSettingsError:
      $ref: '#/components/schemas/GenericError'
    FilterPullRequestsRequest:
      additionalProperties: false
      description: Filters for `/filter/pull_requests`. Empty `properties` passes through all PRs matched by the other filters.
      example:
        account: 1
        date_from: 2020-01-23
        date_to: 2020-05-23
        in:
        - '{1}'
        - github.com/athenianco/athenian-webapp
        stages:
        - wip
        with:
          author:
          - github.com/vmarkovtsev
        exclude_inactive: true
      properties:
        account:
          description: Session account ID.
          type: integer
        date_from:
          description: PRs must be updated later than or equal to this date.
          format: date
          type: string
        date_to:
          description: PRs must be updated earlier than or equal to this date.
          format: date
          type: string
        timezone:
          $ref: '#/components/schemas/TimeZone'
        in:
          $ref: '#/components/schemas/RepositorySet'
        events:
          description: Allowed PR events that happened between `date_from` and `date_to`.
          items:
            $ref: '#/components/schemas/PullRequestEvent'
          type: array
        stages:
          description: Allowed PR stages that are defined at `date_to`.
          items:
            $ref: '#/components/schemas/PullRequestStage'
          type: array
        with:
          $ref: '#/components/schemas/PullRequestWith'
        labels_include:
          description: At least one of these labels must be present in each returned PR.
          items:
            type: string
          type: array
        labels_exclude:
          description: None of these labels must be present in each returned PR.
          items:
            type: string
          type: array
        exclude_inactive:
          description: Value indicating whether PRs without events in the given time frame shall be ignored.
          type: boolean
        jira:
          $ref: '#/components/schemas/JIRAFilter'
        updated_from:
          description: 'Paginate the response: the returned PRs are updated on GitHub no older than this timestamp, including the beginning. Note: "updated on GitHub" means that we don´t consider release or deployment timestamps. Use this field only to paginate after calling `/paginate/pull_requests`. Subject of future changes.'
          format: date
          type: string
        updated_to:
          description: 'Paginate the response: the returned PRs are updated on GitHub no later than this timestamp, not including the ending. Note: "updated on GitHub" means that we don´t consider release or deployment timestamps. Use this field only to paginate after calling `/paginate/pull_requests`. Subject of future changes.'
          format: date
          type: string
        limit:
          description: Maximum number of pull requests to return. The list is sorted by the last update timestamp. `null` means no limit.
          minimum: 1
          type:
          - integer
          - 'null'
        environments:
          description: Target environments for the deployment events, impacts `events` and `stages`. If omitted, we match any deployment in any environment.
          items:
            type: string
          minItems: 1
          type: array
      required:
      - account
      - date_from
      - date_to
      - exclude_inactive
      - in
      type: object
    RepositorySet:
      description: Set of repositories. An empty list raises a bad response 400. Duplicates are automatically ignored.
      example:
      - github.com/athenianco/athenian-webapp
      - github.com/athenianco/athenian-api
      items:
        $ref: '#/components/schemas/RepositoryID'
      type: array
    DeveloperID:
      description: 'User name which uniquely identifies any developer on any service provider.

        The format matches the profile URL without the protocol part.

        '
      example: github.com/vmarkovtsev
      type: string
    NoSourceDataError:
      $ref: '#/components/schemas/GenericError'
    PullRequestStage:
      description: 'PR''s modelled lifecycle stages.

        * `wip`: The PR is a work-in-progress: no reviews, no review requests, not closed.

        * `reviewing`: The PR is going through a review process.

        * `merging`: The PR was approved and is waiting for merge.

        * `releasing`: The PR was merged but is not released yet.

        * `force_push_dropped`: The PR was closed but the Git commit history was rewritten and the PR''s commits no longer exist. Always appears together with `done`.

        * `release_ignored`: The PR belongs to the very first release of the repository, and we suppressed that release according to our heuristics. Always appears together with `done`.

        * `done`: The PR was either closed without merging or released or force push dropped. Deployed or not.

        * `deployed`: The PR was deployed. So it''s merged. Released or not. We respect this stage only when `environment` was specified.'
      enum:
      - wip
      - reviewing
      - merging
      - releasing
      - force_push_dropped
      - done
      - release_ignored
      - deployed
      example: done
      type: string
    TimeZone:
      description: Local time zone offset in minutes, used to adjust `date_from` and `date_to`.
      maximum: 780
      minimum: -720
      type: integer
    InvalidRequestError:
      allOf:
      - $ref: '#/components/schemas/GenericError'
      - properties:
          pointer:
            description: Path to the offending request item.
            example: .granularity
            type: string
        type: object
    DeveloperSet:
      description: A set of developers. An empty list disables the filter and includes everybody. Duplicates are automatically ignored.
      example:
      - github.com/vmarkovtsev
      - github.com/dpordomingo
      items:
        $ref: '#/components/schemas/DeveloperID'
      type: array
    GenericError:
      example:
        detail: 'Unsupported metric: pr-xxx-time'
        status: 400
        title: Bad request syntax or unsupported method.
        type: /errors/InvalidRequestError
      properties:
        detail:
          description: Human-readable explanation specific to this occurrence of the problem.
          example: 'Unsupported metric: pr-xxx-time'
          type: string
        instance:
          description: URI reference that identifies the specific occurrence of the problem. It is `null` for 4xx, Sentry event ID for 5xx.
          example: 2763c4eabd7240f59829ee1a02546293
          type: string
        status:
          description: Duplicated HTTP status code.
          example: 400
          type: integer
        title:
          description: Short, human-readable summary of the problem type.
          example: Bad request syntax or unsupported method.
          type: string
        type:
          description: URI reference that identifies the problem type (RFC 7807).
          example: /errors/InvalidRequestError
          type: string
      required:
      - status
      - title
      - type
      type: object
    PullRequestEvent:
      description: 'PR''s modelled lifecycle events.

        * `created`: The PR was opened.

        * `committed`: Somebody pushed a commit to the PR.

        * `review_requested`: Somebody requested a PR review.

        * `reviewed`: Somebody reviewed the PR (either approved, requested changes, or commented).

        * `approved`: Somebody approved the PR. Note that if there were negative reviews from other participants, an approval does *not* trigger this event.

        * `changes_requested`: Somebody submitted a negative PR review.

        * `merged`: Somebody merged the PR.

        * `released`: The PR was released.

        * `rejected`: Somebody closed the PR without merging.

        * `deployed`: The PR was deployed. We respect this event only when `environment` was specified.'
      enum:
      - created
      - committed
      - review_requested
      - reviewed
      - approved
      - changes_requested
      - merged
      - released
      - rejected
      - deployed
      example: created
      type: string
    PullRequestPaginationPlan:
      additionalProperties: false
      description: Response of `/paginate/pull_requests`. Computed split of the PR updated timestamp range.
      example:
        updated:
        - 2020-10-08
        - 2020-10-07
        - 2020-10-01
      properties:
        updated:
          description: Split borders in *descending* order.
          items:
            format: date
            type: string
          type: array
      type: object
  responses:
    InvalidRequestErrorResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InvalidRequestError'
      description: The request is invalid.
  securitySchemes:
    apiKeyAuth:
      description: 'Authorization by the value of `X-API-Key` header aka API token.

        The tokens are user- and account-specific. Create them by calling `/token/create`.

        The server automatically inserts `account` in the request''s body if it was not

        supplied by the user.'
      in: header
      name: X-API-Key
      type: apiKey
      x-apikeyInfoFunc: athenian.api.controllers.security_controller.info_from_apiKeyAuth
    bearerAuth:
      bearerFormat: JWT
      description: 'Regular JSON Web Token authorization powered by Auth0.

        The server expects an `Authorization: Bearer <token>` header and checks `<token>` by

        sending it to Auth0. Visit [{{ server_url | replace("api", "app") }}/bearer]({{ server_url | replace("api", "app") }}/bearer)

        to copy your current JWT that will expire within 24 hours.'
      scheme: bearer
      type: http
      x-bearerInfoFunc: athenian.api.controllers.security_controller.info_from_bearerAuth