openapi: 3.2.0
info:
  description: REST API for the Clinical Knowledge Manager.
  version: 1.6.0
  title: CKM REST Projects API
  contact:
    name: CKM Support
    url: https://oceanehr.atlassian.net/servicedesk/customer/portal/15
    email: ckm@oceaninformatics.com
servers:
- url: /ckm/rest/v1
tags:
- name: Projects
  description: Endpoint for project-related services, including listing and getting projects.
paths:
  /projects/{cid-project}:
    get:
      tags:
      - Projects
      summary: Gets the specified CKM project
      description: ''
      operationId: getProject
      parameters:
      - name: cid-project
        in: path
        description: The citeable identifier of the project.
        required: true
        schema:
          type: string
      security:
      - basicAuth: []
      - sessionid: []
      responses:
        '200':
          description: Successful retrieval of the main data of the requested project.
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/Project'
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '400':
          description: General bad request.
        '404':
          description: Project with the specified cid-project could not be found (or is private and the specified user, if any, does not have the necesary permissions.
  /projects:
    get:
      tags:
      - Projects
      summary: Lists all or a selection of CKM projects (full projects and incubators)
      description: ''
      operationId: listProjects
      parameters:
      - name: cid-subdomain
        in: query
        description: Set to only list projects of the specified subdomain.
        required: false
        schema:
          type: string
      - name: project-type
        in: query
        description: Set to only list projects of this type (full projects or incubators).
        required: false
        schema:
          type: string
          enum:
          - PROJECT
          - INCUBATOR
      - name: include-order-template-projects
        in: query
        description: True to list order template projects as well, false to exclude such projects. Defaults to true.
        required: false
        schema:
          type: boolean
          default: true
      - name: my-projects-only
        in: query
        description: Set to true to only list projects where the current user has any explicit role such as member or editor. Defaults to false.
        required: false
        schema:
          type: boolean
          default: false
      - name: my-editor-projects-only
        in: query
        description: Set to true to only list projects where the current user is an explicit editor of. Defaults to false.
        required: false
        schema:
          type: boolean
          default: false
      - name: show-all-to-admin
        in: query
        description: True to list all applable projects for CKAs and technical administrators, even if they are not an explicit editor of it and my-editor-projects-only is set to true. This enables a convient way of retrieving all projects the user has editing rights for, either because the user is an explicit editor of the project or a CKM-wide admin. Defaults to true.
        required: false
        schema:
          type: boolean
          default: true
      security:
      - basicAuth: []
      - sessionid: []
      responses:
        '200':
          description: Successful retrieval of the main data of all requested projects.
          content:
            application/xml:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Project'
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Project'
        '400':
          description: General bad request.
        '404':
          description: Not found. E.g. if a subdomain cid was specified (and is structurally valid), but does not exist.
components:
  schemas:
    Project:
      type: object
      properties:
        cid:
          type: string
        name:
          type: string
        projectURL:
          type: string
        cidSubdomain:
          type: string
        subdomainName:
          type: string
        public:
          type: boolean
        projectType:
          type: string
          enum:
          - PROJECT
          - INCUBATOR
        remoteSubdomain:
          type: boolean
        forOrderTemplates:
          type: boolean
  securitySchemes:
    sessionid:
      description: Once the session id is known, it can be used for authentication until expired. The provided session id is used (and validated) on making an actual request.
      type: apiKey
      name: JSESSIONID
      in: header
    basicAuth:
      type: http
      scheme: basic
      description: Basic authentification using the CKM username and password. The provided credentials are used (and validated) on making an actual request.
externalDocs:
  description: Find out more about openEHR and the Clinical Knowledge Manager (CKM)
  url: http://www.openehr.org