# Template for the first version of a new domain API.
# Copy it to docs/05-interfaces/<system>/domains/<domain>/v1/openapi.yaml, replace every <...>,
# and replace the example resource with the domain's own. The rules it follows are in
# docs/05-interfaces/choosing-an-interface.md.
openapi: 3.1.0
info:
  title: <System> <Domain> API
  version: 1.0.0
  description: <What this domain covers, in one or two sentences.>
servers:
- url: https://<system>.moonitoring.com/<domain>/v1
  description: Prod
- url: https://stage-<system>.moonitoring.com/<domain>/v1
  description: Stage, through IAP
security:
- bearer: []
paths:
  /examples:
    get:
      summary: List examples
      operationId: listExamples
      parameters:
      - $ref: ../../../../common/v1/schemas.yaml#/components/parameters/Cursor
      - $ref: ../../../../common/v1/schemas.yaml#/components/parameters/Limit
      responses:
        '200':
          description: One page of examples.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Example'
                  next_cursor:
                    type: string
                    description: Where the next page starts; absent on the last page.
                required:
                - items
        '401':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Unauthorized
        '403':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Forbidden
    post:
      summary: Create an example
      operationId: createExample
      parameters:
      - $ref: ../../../../common/v1/schemas.yaml#/components/parameters/IdempotencyKey
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Example'
      responses:
        '201':
          description: The example was created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Example'
        '400':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/BadRequest
        '409':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/Conflict
  /examples/{example_id}:
    get:
      summary: Read one example
      operationId: getExample
      parameters:
      - name: example_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: The example.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Example'
        '404':
          $ref: ../../../../common/v1/schemas.yaml#/components/responses/NotFound
components:
  schemas:
    Example:
      description: <What one record of this resource is.>
      type: object
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        name:
          type: string
      required:
      - id
      - name
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: The short-lived token signed by `access`.