openapi.yaml

swagger: "2.0"

info:
  title: OKR Tracker API
  description: API for updating KPIs and key results.
  version: 2.1.0
  contact:
    name: Dataspeilet
    url: https://okr.oslo.systems
    email: annemerete.pettersen@origo.oslo.kommune.no
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
host: <host>
schemes:
  - https
produces:
  - application/json
x-google-backend:
  address: https://<location>-<project-id>.cloudfunctions.net/<CF-location>
  path_translation: APPEND_PATH_TO_ADDRESS
  protocol: h2
security:
  - apiKey: []

paths:
  /kpi:
    get:
      summary: Get KPIs.
      operationId: getKPIs
      description: >
        This endpoint employs cursor pagination for improved response handling
        for both the server and the client. The cursor token needed for
        subsequent requests is included in the response until all data is
        exhausted.
      parameters:
        - name: limit
          in: query
          type: integer
          required: false
          default: 50
          description: The number of results per page (1 - 50)
        - name: cursor
          in: query
          type: string
          required: false
          default: null
          description: Pagination cursor
        - name: order
          in: query
          type: string
          required: false
          default: asc
          description: Sort order based on creation date
      responses:
        200:
          $ref: '#/responses/PaginatedKpis'
        400:
          $ref: '#/responses/BadRequest'
        500:
          $ref: '#/responses/Unavailable'
  /kpi/{id}:
    get:
      summary: Get KPI.
      operationId: getKPI
      parameters:
        - name: id
          in: path
          description: KPI Id
          required: true
          type: string
      responses:
        200:
          description: A successful response
          schema:
            $ref: '#/definitions/Kpi'
        404:
          $ref: '#/responses/NotFound'
        500:
          $ref: '#/responses/Unavailable'
    post:
      summary: Post KPI progression.
      operationId: postKPI
      security:
        - apiKey: []
          apiClientId: []
          apiClientSecret: []
      parameters:
        - name: id
          in: path
          description: KPI Id
          required: true
          type: string
        - name: progress
          in: body
          required: true
          description: Progression value
          schema:
            type: object
            properties:
              progress:
                type: number
              comment:
                type: string
            example:
              progress: 123
              comment: A fine measurement
      responses:
        '200':
          description: A successful response
          schema:
            type: string
            example: "Updated KPI (${id}) with progress: ${progress}"
        400:
          $ref: '#/responses/BadRequest'
        404:
          $ref: '#/responses/NotFound'
        500:
          $ref: '#/responses/Unavailable'
  /kpi/{id}/values:
    get:
      summary: Get KPI progression history.
      operationId: getKPIProgressionValues
      parameters:
        - name: id
          in: path
          description: KPI Id
          required: true
          type: string
      responses:
        200:
          description: A successful response
          schema:
            type: array
            items:
              $ref: '#/definitions/KpiMeasurement'
        404:
          $ref: '#/responses/NotFound'
        500:
          $ref: '#/responses/Unavailable'
  /kpi/{id}/values/{date}:
    parameters:
      - name: id
        in: path
        description: KPI Id
        required: true
        type: string
      - name: date
        in: path
        description: Date
        required: true
        type: string
        format: date
    put:
      summary: Create or update KPI progression value.
      operationId: updateKPIProgressionValue
      security:
        - apiKey: []
          apiClientId: []
          apiClientSecret: []
      parameters:
        - name: value
          in: body
          required: true
          description: Progression value
          schema:
            type: object
            properties:
              value:
                type: number
              comment:
                type: string
            example:
              value: 123
              comment: A fine measurement
      responses:
        200:
          description: A successful response
          schema:
            type: object
            properties:
              message:
                type: string
        400:
          $ref: '#/responses/BadRequest'
        404:
          $ref: '#/responses/NotFound'
        500:
          $ref: '#/responses/Unavailable'
    delete:
      summary: Delete KPI progression value.
      operationId: deleteKPIProgressionValue
      security:
        - apiKey: []
          apiClientId: []
          apiClientSecret: []
      responses:
        200:
          description: A successful response
          schema:
            type: object
            properties:
              message:
                type: string
        400:
          $ref: '#/responses/BadRequest'
        404:
          $ref: '#/responses/NotFound'
        500:
          $ref: '#/responses/Unavailable'
  /keyres/{id}:
    get:
      summary: Get key result.
      operationId: getKeyRes
      parameters:
        - name: id
          in: path
          description: Key result Id
          required: true
          type: string
      responses:
        '200':
          description: A successful response
          schema:
            $ref: '#/definitions/Keyres'
        404:
          $ref: '#/responses/NotFound'
        500:
          $ref: '#/responses/Unavailable'
    post:
      summary: Post key result progression.
      operationId: postKeyRes
      security:
        - apiKey: []
          apiClientId: []
          apiClientSecret: []
      parameters:
        - name: id
          in: path
          description: Key res Id
          required: true
          type: string
        - name: progress
          in: body
          required: true
          description: Progression value
          schema:
            type: object
            properties:
              progress:
                type: number
              comment:
                type: string
            example:
              progress: 123
              comment: A fine measurement
        - name: okr-team-secret
          in: header
          description: Identify yourself with the secret you chose in your Team's settings
          type: string
      responses:
        '200':
          description: A successful response
          schema:
            type: string
            example: "Updated Key result (${id}) with progress: ${progress}"
        400:
          $ref: '#/responses/BadRequest'
        404:
          $ref: '#/responses/NotFound'
        500:
          $ref: '#/responses/Unavailable'
  /user/{id}:
    patch:
      summary: Update user details.
      operationId: patchUser
      security:
        - apiKey: []
          okrAdminSecret: []
      parameters:
        - name: id
          in: path
          description: User ID
          required: true
          type: string
        - name: details
          in: body
          required: true
          description: User details
          schema:
            type: object
            properties:
              displayName:
                type: string
              position:
                type: string
            example:
              displayName: Foo Bar
              position: director
      responses:
        '200':
          description: A successful response
          schema:
            type: string
            example: "User updated"
        '400':
          $ref: '#/responses/BadRequest'
        '401':
          $ref: '#/responses/Unauthorized'
        '404':
          $ref: '#/responses/NotFound'
        '500':
          $ref: '#/responses/Unavailable'

securityDefinitions:
  apiKey:
    type: apiKey
    name: x-api-key
    in: header
  apiClientId:
    type: apiKey
    name: okr-client-id
    in: header
    description: Identify yourself with the identifier of your API client
  apiClientSecret:
    type: apiKey
    name: okr-client-secret
    in: header
    description: Identify yourself with the secret of your API client
  okrAdminSecret:
    type: apiKey
    name: okr-admin-secret
    in: header

definitions:
  Keyres:
    properties:
      currentValue:
        type: number
      progression:
        type: number
      description:
        type: string
      created:
        type: string
        format: date-time
      edited:
        type: string
        format: date-time
      createdBy:
        type: string
      editedBy:
        type: string
      lastUpdated:
        type: object
        properties:
          value:
            type: number
          timestamp:
            type: string
            format: date-time
          comment:
            type: string
          createdBy:
            type: string
  Kpi:
    properties:
      id:
        type: string
      currentValue:
        type: number
      name:
        type: string
      description:
        type: string
      type:
        type: string
      parent:
        type: object
        properties:
          slug:
            type: string
          name:
            type: string
      created:
        type: string
        format: date-time
      edited:
        type: string
        format: date-time
      createdBy:
        type: string
      editedBy:
        type: string
      lastUpdated:
        type: object
        properties:
          value:
            type: number
          timestamp:
            type: string
            format: date-time
      updateFrequency:
        type: string
        enum: [daily, weekly, monthly, quarterly, annual, irregular]
      isStale:
        type: boolean
        example: false
  KpiMeasurement:
    type: object
    properties:
      value:
        type: number
      date:
        type: string
        format: date
      comment:
        type: string
      created:
        type: string
        format: date-time
      createdBy:
        type: string
      edited:
        type: string
        format: date-time
      editedBy:
        type: string
  Pagination:
    properties:
      limit:
        type: integer
        example: 25
      order:
        type: string
        example: asc
      results_count:
        type: integer
        example: 25
      cursor:
        type: string
      next_cursor:
        type: string

responses:
  PaginatedKpis:
    description: Paginated KPI list
    schema:
      type: object
      properties:
        pagination:
          $ref: '#/definitions/Pagination'
        results:
          type: array
          items:
            $ref: '#/definitions/Kpi'
  NotFound:
    description: Resource not found
    schema:
      type: object
      properties:
        message:
          type: string
  Unauthorized:
    description: Unauthorized for the requested operation on the resource
    schema:
      type: object
      properties:
        message:
          type: string
  Unavailable:
    description: Something went wrong
    schema:
      type: object
      properties:
        message:
          type: string
  BadRequest:
    description: A bad request
    schema:
      type: object
      required:
        - message
      properties:
        errors:
          type: object
        message:
          type: string