openapi: 3.0.3
info:
  title: Zorg op Orde API
  description: |-
    Copyright Zorg op Orde – All rights reserved.
    
    Security is done, for now, via cookies - i.e. just make the API request,
    if done from a browser session that is logged in, the API request is handled.
    
    All API requests can return an error state of 'not logged in' or 'not authorized'
    (which means, some user is logged in, but is not allowed to see / act the thing they want to see / act on).
  contact:
    name: Zorg op Orde tech lead
    email: r.zwitserloot@zorgoporde.nl
  version: 0.1-DEV
externalDocs:
  description: Find out more about Swagger
  url: http://swagger.io
servers:
  - url: https://tools.zorgoporde.nl/api1
    description: Production
  - url: https://test.zorgoporde.nl/api1
    description: Testing
tags:
  - name: core
    description: |-
      Functionality that cross-cuts API concerns, such as authentication.
      TBD.

  - name: QoC
    description: |-
      API related to Quality of Care features
      
      A care program (dutch: _ketenzorg_ or _zorgprogramma_) describes a specific disease (such as Diabetes or Astma) or a more abstract concern such as elderly care or 
general concern about cardiovascular health. The same care program can show up multiple times, as there are different care programs and standards for the same disease or 
concern. For example, there could be the InEen report 'take' on how one should provide Diabetes care, and there could be some regional group's slightly different take on it; 
these would show up as different care programs.

      Any given customer has a 'fave' status for any given care program; some care programs are enabled by default and some are disabled by default. However, a customer can 
explicitly select a program they wouldn't ordinarily see ('favourite' it), or explicitly deselect a program they get by default ('unfavourite' it). Most care programs will 
be neither favourited nor unfavourited: They should be shown based on their `default_show` property.

      To allow favouriting/unfavouriting, the front end has 2 separate views for selecting care programs: The usual view, which shows _only_:
      - Care programs that customer has explicitly favourited.
      - Care programs that are shown by default to this customer which they did not explicitly unfavourite.

      As well as a 'config' view where they see _all_ care programs that could possibly be relevant for that customer, where the customer can preview the report 
(essentially, run the report as normal), favourite something they don't get by default, or unfavourite something they get by default.
paths:
  /qoc/careprogram/list:
    get:
      tags:
        - QoC
      summary: List all available care programs
      description: Includes all care programs that the user is allowed to see, even ones that are unfavourited or not shown by default.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items: 
                  $ref: '#/components/schemas/CareProgram'
        '401':
          $ref: '#/components/responses/NoAuth'
        '403':
          $ref: '#/components/responses/NoAccess'


components:
  schemas:
    CareProgram:
      type: object
      properties:
        name:
          description: Human readable text in dutch, guaranteed to be quite short.
          type: string
          example: Diabetes Mellitus type 2 (ZEL)
        description:
          description: in dutch and in *HTML*, can consist of multiple paragraphs, but won't be more than ~5 lines or so.
          type: string
          example: Ketenzorg DM2 volgens de standaard werkwijze van zorgggroep ZEL.
        default_show:
          description: If `true`, show this unless explicitly unfavourited. If `false`, do not show unless explicitly favourited.
          type: boolean
        fav_state:
          description: If `T`, always show this. If `F`, never show it. If `X`, show if `default_show` is `true`.
          type: string
          example: X
          enum:
            - T
            - F
            - X
        reports:
          description: |-
            A care program offers 1 or more reports; any given report is generally very different from another.
            Each offered report should be shown as a button.
          type: array
          items:
            type: object
            properties:
              type:
                oneOf:
                - description: An indicator set report. use the `/qol/indicatorset` API endpoint.
                  type: string
                  example: indicatorset
                - description: Resolve by loading the URL in the `url` property (`window.location = ` style).
                  type: string
                  example: link
              name:
                description: Short description in dutch text; show this in the button.
                type: string
                example: Indicatoren
              url:
                description: >-
                  Only for `type: "link"`.
                type: string
                example: '/indicators/casefinder?t=dm'
              key:
                description: >-
                  Only for `type: "indicatorset"`. Pass to `/qoc/indicatorset` API.
                type: string
                example: ZEL-dm2


  responses:
    NoAuth:
      description: User is not logged in / session expired.
    NoAccess:
      description: User is not allowed to access this API endpoint.