openapi: 3.2.0
info:
  title: Reference API
  description: API to manage your %product% resources programmatically. Using these APIs, you are able to manage pages, integrate with CI/CD, and retrieve resources among other operations.
  contact: {}
  version: 1.1.0
servers:
- url: https://api.developerhub.io/api/v1
  variables: {}
security:
- Api-Key: []
tags:
- name: Reference
  description: Operations for adding, reading, and publishing API reference specifications.
paths:
  /version/{versionId}/reference:
    post:
      tags:
      - Reference
      summary: Adds or updates a reference specification
      description: 'Adds or updates a reference specification in that version. If the reference title matches one that already existed, then it is updated. Rate limit: 300 in 60 minutes.'
      operationId: add_reference
      parameters:
      - name: versionId
        in: path
        description: The version ID
        required: true
        style: simple
        schema:
          type: string
      - name: publish
        in: query
        description: Publish the specification immediately. Set to false to import it as a draft to be published later.
        required: false
        schema:
          type: boolean
          default: true
      - name: show_try_it_out
        in: query
        description: Enable the Try It Out console on the reference
        required: false
        schema:
          type: boolean
      - name: allow_download
        in: query
        description: Allow readers to download the specification
        required: false
        schema:
          type: boolean
      - name: expandable
        in: query
        description: Show the reference operations as expandable rows
        required: false
        schema:
          type: boolean
      requestBody:
        content:
          multipart/form-data:
            encoding: {}
            schema:
              type: object
              required:
              - file
              properties:
                file:
                  type: string
                  description: The API specification in OpenAPI 2/3 (Swagger) format
                  format: binary
        required: false
      responses:
        '201':
          description: Created
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Reference'
        '400':
          description: General Exception
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDenied'
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TooManyRequests'
      deprecated: false
  /reference/{id}/definition:
    get:
      tags:
      - Reference
      summary: Read a reference specification
      description: 'Downloads the raw specification of an API reference in JSON or YAML. Rate limit: 600 in 1 minute.'
      operationId: read_reference_definition
      parameters:
      - name: id
        in: path
        description: Reference ID
        required: true
        schema:
          type: integer
      - name: draft
        in: query
        description: Read the draft specification instead of the published one
        required: false
        schema:
          type: boolean
          default: false
      - name: format
        in: query
        description: Format of the returned specification. `auto` returns it as originally uploaded; `json` and `yaml` convert it if needed.
        required: false
        schema:
          type: string
          default: auto
          enum:
          - auto
          - json
          - yaml
      responses:
        '200':
          description: OK
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
          content:
            application/json:
              schema:
                type: object
                description: The specification as a JSON document
            text/yaml:
              schema:
                type: string
                description: The specification as a YAML document
        '403':
          description: Access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDenied'
        '404':
          description: Draft not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TooManyRequests'
      deprecated: false
  /reference/{id}/publish:
    put:
      tags:
      - Reference
      summary: Publish a reference draft
      description: 'Publishes the draft specification of an API reference. Fails if the reference has no draft. Rate limit: 300 in 60 minutes.'
      operationId: publish_reference
      parameters:
      - name: id
        in: path
        description: Reference ID
        required: true
        schema:
          type: integer
      responses:
        '201':
          description: Published
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Reference'
        '400':
          description: General Exception
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDenied'
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TooManyRequests'
      deprecated: false
components:
  schemas:
    Reference:
      title: Reference
      required:
      - id
      - title
      - created
      - updated
      - slug
      - ordr
      type: object
      properties:
        id:
          type: integer
          description: Unique identifier
          example: 5
        title:
          type: string
          description: Title of the API Reference
          example: DeveloperHub.io API
        created:
          type: string
          description: Date of creation
          example: 2019-03-20T19:02:14+0000
        updated:
          type: string
          description: Date of last update
          example: 2019-03-20T19:02:14+0000
        slug:
          type: string
          description: Slug in the URL
          example: developerhub.io-api
        ordr:
          type: integer
          description: Numerical order in the version
          example: 1
      description: Reference object
    Error:
      title: Error
      type: object
      properties:
        message:
          type: string
          description: Message of the error
          example: No file provided.
        httpCode:
          type: number
          description: HTTP code returned
          example: 400
        code:
          type: number
          description: Internal error code
          example: 400
    AccessDenied:
      title: AccessDenied
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              description: Message of the error
              example: Access Denied
            httpCode:
              type: number
              description: HTTP code returned
              example: 403
            code:
              type: number
              description: Internal error code
              example: 403
    TooManyRequests:
      title: TooManyRequests
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              description: Message of the error
              example: You exceeded the rate limit
            httpCode:
              type: number
              description: HTTP code returned
              example: 429
            code:
              type: number
              description: Internal error code
              example: 9
  headers:
    X-RateLimit-Remaining:
      description: Requests consumed in current period
      schema:
        type: integer
        example: 253
    X-RateLimit-Reset:
      description: Unix timestamp at which requests consumed will reset
      schema:
        type: integer
        example: 1611530395
    X-RateLimit-Limit:
      description: Requests permitted until reset time
      schema:
        type: integer
        example: 300
  securitySchemes:
    Api-Key:
      type: apiKey
      description: 'Generate an API Key from [DeveloperHub.io platform](https://app.developerhub.io) and provide it in the header such as `--header "X-Api-Key: <api-key>"` for cURL for all the requests requiring this authentication.'
      name: X-Api-Key
      in: header