mikaelvesavuori/catalogist

openapi: 3.0.0
info:
  version: 3.0.0
  title: Catalogist
  description: Catalogist is the easy way to catalog and make your software and (micro)services visible to your organization in a lightweight and developer-friendly way.

servers:
  - url: https://RANDOM.execute-api.REGION.amazonaws.com
    description: API server

paths:
  /record:
    get:
      description: Get record
      operationId: getRecord
      responses:
        default:
          $ref: '#/components/responses/401'
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Manifest'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '406':
          $ref: '#/components/responses/406'
        '429':
          $ref: '#/components/responses/429'
      parameters:
        - in: query
          name: repo
          description: What is the name of the repository (e.g. "someorg/somerepo")?
          required: true
          schema:
            type: string
        - in: query
          name: service
          description: What is the name of the service?
          required: false
          schema:
            type: string
      security:
        - apiKey: []
    post:
      description: Create record
      operationId: createRecord
      responses:
        default:
          $ref: '#/components/responses/403'
        '204':
          description: Successful response
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '406':
          $ref: '#/components/responses/406'
        '429':
          $ref: '#/components/responses/429'
      requestBody:
        $ref: '#/components/requestBodies/CreateRecord'
      security:
        - apiKey: []

components:
  securitySchemes:
    apiKey:
      type: apiKey
      name: Authorization
      in: header
  schemas:
    Manifest:
      type: object
      additionalProperties: false
      properties:
        spec:
          $ref: '#/components/schemas/Spec'
        relations:
          $ref: '#/components/schemas/Relations'
        support:
          $ref: '#/components/schemas/Support'
        slo:
          $ref: '#/components/schemas/Slo'
        api:
          $ref: '#/components/schemas/Api'
        metadata:
          $ref: '#/components/schemas/Metadata'
        links:
          $ref: '#/components/schemas/Links'
    Spec:
      type: object
      required:
        - repo
        - name
      additionalProperties: false
      properties:
        repo:
          type: string
          description: Name of the repository where the code base is stored.
          minLength: 1
          maxLength: 500
          example: someorg/somerepo
        name:
          type: string
          description: Name of the component.
          minLength: 1
          maxLength: 500
          example: my-service
        description:
          type: string
          description: Describes the component.
          minLength: 1
          maxLength: 1500
          example: My Service handles all the transactions for my book club
        kind:
          type: string
          description: Describes which type of solution this is.
          enum:
            - service
            - api
            - component
            - cots
            - product
            - external
            - other
        lifecycleStage:
          type: string
          description: The lifecycle stage this component is in.
          minLength: 1
          maxLength: 500
          example: prod
        version:
          type: string
          description: The version of the component.
          minLength: 1
          maxLength: 500
          example: 1.0.0
        responsible:
          type: string
          description: An individual that is responsible for this component.
          minLength: 1
          maxLength: 500
          example: Someguy Someguyson
        team:
          type: string
          description: The team responsible for this component.
          minLength: 1
          maxLength: 500
          example: ThatAwesomeTeam
        system:
          type: string
          description: The system this component is part of.
          minLength: 1
          maxLength: 500
          example: Transactions
        domain:
          type: string
          description: The domain this component is part of.
          minLength: 1
          maxLength: 500
          example: BookClub
        dataSensitivity:
          type: string
          description: The level of data sensitivity.
          enum:
            - public
            - internal
            - secret
            - other
        tags:
          type: array
          description: An optional list of tags.
          maxItems: 20
          items:
            type: string
            minLength: 1
            maxLength: 500
    Relations:
      type: array
      maxItems: 50
      items:
        type: string
        minLength: 1
        maxLength: 500
    Support:
      type: object
      additionalProperties:
        type: string
        minLength: 1
        maxLength: 500
    Slo:
      type: array
      maxItems: 20
      items:
        $ref: '#/components/schemas/SloItem'
    SloItem:
      type: object
      description: Service level objective (SLO) information.
      required:
        - description
        - type
        - target
        - period
      properties:
        description:
          type: string
          description: Describes what the SLO does and measures.
          minLength: 1
          maxLength: 500
        type:
          type: string
          description: What type of SLO is this?
          enum:
            - latency
            - availability
            - correctness
            - other
        implementation:
          type: string
          description: Optional implementation query.
          minLength: 1
          maxLength: 1500
        target:
          type: string
          description: Compliance target, typically described as a percentage, percentile, or duration.
          minLength: 1
          maxLength: 500
          example: "99.9%"
        period:
          type: number
          description: Compliance period in days.
    Api:
      type: array
      maxItems: 20
      items:
        $ref: '#/components/schemas/ApiItem'
    ApiItem:
      type: object
      required:
        - name
      additionalProperties:
        type: string
        minLength: 1
        maxLength: 500
      properties:
        name:
          type: string
          description: Name of the API.
          minLength: 1
          maxLength: 500
        schemaPath:
          type: string
          description: Path to a schema or definition of the API.
          minLength: 1
          maxLength: 500
    Metadata:
      type: object
      additionalProperties:
        type: string
        minLength: 1
        maxLength: 500
    Links:
      type: array
      maxItems: 20
      items:
        $ref: '#/components/schemas/LinkItem'
    LinkItem:
      type: object
      additionalProperties: false
      required:
        - url
        - title
        - icon
      properties:
        url:
          type: string
          description: URL for the link.
          minLength: 1
          maxLength: 500
        title:
          type: string
          description: Title and description of the link.
          minLength: 1
          maxLength: 500
        icon:
          type: string
          description: What type of icon should represent this?
          enum:
            - web
            - api
            - service
            - documentation
            - task
            - dashboard
            - other

  requestBodies:
    CreateRecord:
      description: Create record request body
      required: true
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Manifest"

  responses:
    "401":
      description: Unauthorized
      content:
        text/plain:
          schema:
            title: Unauthorized
            type: string
            example: Unauthorized
    "403":
      description: Forbidden
      content:
        text/plain:
          schema:
            title: Forbidden
            type: string
            example: Forbidden
    "404":
      description: Not found
      content:
        text/plain:
          schema:
            title: Not found
            type: string
            example: Not found
    "406":
      description: Not acceptable
      content:
        text/plain:
          schema:
            title: Not acceptable
            type: string
            example: Not acceptable
    "429":
      description: Too many requests
      content:
        text/plain:
          schema:
            title: Too many requests
            type: string
            example: Too many requests