Complexity Of Need API Specification.yaml

---
openapi: 3.0.3
info:
  title: Complexity of Need API
  version: v1
  description: |
    A microservice which holds the Complexity of Need level associated with offenders

    ### Authentication

    This API is secured by OAuth 2 with tokens supplied by HMPPS Auth.

    Read permissions are granted to clients with the role `ROLE_COMPLEXITY_OF_NEED`

    Write permissions are granted to clients with the role `ROLE_UPDATE_COMPLEXITY_OF_NEED`.

    ---

    Owned by the **Manage POM Cases** team

    - Slack: [#manage-pom-cases](https://mojdt.slack.com/channels/manage-pom-cases)
    - GitHub: [ministryofjustice/hmpps-complexity-of-need](https://github.com/ministryofjustice/hmpps-complexity-of-need)
security:
- HmppsAuth:
  - read
components:
  responses:
    ContentFound:
      description: Request successfully processed - content found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/successResponse'
    IncorrectRequest:
      description: The request was not formed correctly
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
    Unauthorised:
      description: The client does not have authorisation to make this request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
  securitySchemes:
    HmppsAuth:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: 'http://hmpps_oauth_service.com'
          scopes:
            'write:CL': write CL entries
            'read:CL': read CL entries
  parameters:
    prisonReferenceNumber:
      name: prn
      description: NOMIS Prison Reference Number
      in: query
      schema:
        type: string
    fromDate:
      name: fromDate
      in: query
      description: Optional parameter denoting minimum date of event occurrence which should be returned in the response
      schema:
        type: string
        format: date
    toDate:
      name: toDate
      in: query
      description: Optional parameter denoting maximum date of event occurrence which should be returned in the response
      schema:
        type: string
        format: date
  schemas:
    Level:
      type: string
      enum:
      - low
      - medium
      - high
      description: Complexity of Need Level
      example: low
    OffenderNo:
      type: string
      description: NOMIS Offender Number
      example: A0000AA
    ComplexityOfNeed:
      type: object
      properties:
        offenderNo:
          "$ref": "#/components/schemas/OffenderNo"
        level:
          "$ref": "#/components/schemas/Level"
        sourceUser:
          type: string
          description: The NOMIS username that supplied this Complexity of Need entry
          example: JSMITH_GEN
        sourceSystem:
          type: string
          description: The OAuth Client ID of the system that created this entry
          example: hmpps-api-client-id
        notes:
          type: string
          description: Free-text notes for this entry
        createdTimeStamp:
          type: string
          format: date_time
          description: The date & time this entry was created (in RFC 3339 format)
          example: '2021-03-02T17:18:46.457Z'
        active:
          type: boolean
          description: Whether it is active or not
      required:
      - offenderNo
      - level
      - createdTimeStamp
      - sourceSystem
      additionalProperties: false
    NewComplexityOfNeed:
      type: object
      properties:
        level:
          "$ref": "#/components/schemas/Level"
        sourceUser:
          type: string
          description: The NOMIS username that supplied this Complexity of Need entry
          example: JSMITH_GEN
        notes:
          type: string
          description: Free-text notes for this entry
      required:
      - level
      additionalProperties: false
    successResponse:
      properties:
        content:
          type: object
          additionalProperties: true
    errorResponse:
      properties:
        developerMessage:
          type: string
        errorCode:
          type: integer
        status:
          type: integer
        userMessage:
          type: string
tags:
- name: Single Offender
  description: Access Complexity of Need for a single offender
- name: Multiple Offenders
  description: Access Complexity of Need for multiple offenders at once
paths:
  "/v1/complexity-of-need/offender-no/{offender_no}":
    parameters:
    - name: offender_no
      in: path
      description: NOMIS Offender Number
      example: A0000AA
      required: true
      schema:
        type: string
    get:
      summary: Retrieve the current Complexity of Need level for an offender
      tags:
      - Single Offender
      responses:
        '200':
          description: Offender's current Complexity of Need level found
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ComplexityOfNeed"
        '401':
          description: Invalid or missing access token
        '403':
          description: Access token is missing necessary role
        '404':
          description: The Complexity of Need level for this offender is not known
    post:
      summary: Update the Complexity of Need level for an offender
      tags:
      - Single Offender
      description: 'Clients calling this endpoint must have role: `ROLE_UPDATE_COMPLEXITY_OF_NEED`'
      parameters: []
      responses:
        '200':
          description: Complexity of Need level set successfully
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ComplexityOfNeed"
        '400':
          description: There were validation errors. Make sure you've given a valid
            level.
        '401':
          description: Invalid or missing access token
        '403':
          description: Access token is missing role `ROLE_COMPLEXITY_OF_NEED`
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/NewComplexityOfNeed"
  "/v1/complexity-of-need/multiple/offender-no":
    post:
      summary: Retrieve the current Complexity of Need levels for multiple offenders
      tags:
      - Multiple Offenders
      description: |
        This endpoint returns a JSON array containing the current Complexity of Need entry for multiple offenders.

        The response array:
          - will exclude offenders whose Complexity of Need level is not known (i.e. these would result in a `404 Not Found` error on the single `GET` endpoint)
          - will exclude offenders without a current active level
          - is not sorted in the same order as the request body
          - is not paginated
      parameters: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/ComplexityOfNeed"
        '400':
          description: The request body was invalid. Make sure you've provided a JSON
            array of NOMIS Offender Numbers.
        '401':
          description: Invalid or missing access token
        '403':
          description: Access token is missing necessary role
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                "$ref": "#/components/schemas/OffenderNo"
              description: A JSON array of NOMIS Offender Numbers
              example:
              - A0000AA
              - B0000BB
              - C0000CC
  "/v1/complexity-of-need/offender-no/{offender_no}/history":
    parameters:
    - name: offender_no
      in: path
      description: NOMIS Offender Number
      example: A0000AA
      required: true
      schema:
        type: string
    get:
      summary: Retrieve full history of Complexity of Needs for an offender
      tags:
      - Single Offender
      description: Results are sorted chronologically (newest first, oldest last)
      responses:
        '200':
          description: Offender's Complexity of Need history found
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/ComplexityOfNeed"
        '401':
          description: Invalid or missing access token
        '403':
          description: Access token is missing necessary role
        '404':
          description: The Complexity of Need level for this offender is not known
  "/v1/complexity-of-need/offender-no/{offender_no}/inactivate":
    parameters:
    - name: offender_no
      in: path
      description: NOMIS Offender Number
      example: A0000AA
      required: true
      schema:
        type: string
    put:
      summary: Inactivate the Complexity of Need level for an offender
      tags:
      - Single Offender
      description: 'Clients calling this endpoint must have role: `ROLE_UPDATE_COMPLEXITY_OF_NEED`'
      responses:
        '200':
          description: Complexity of Need level inactivated successfully
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ComplexityOfNeed"
        '401':
          description: Invalid or missing access token
        '403':
          description: Access token is missing role `ROLE_COMPLEXITY_OF_NEED`
  "/subject-access-request":
    get:
      summary: API call to retrieve SAR data from a product
      tags:
        - Subject Access Request
      description: |
        NOMIS Prison Number (PRN) must be provided as part of the request.
        * If the product uses the identifier type transmitted in the request, it can respond with its data and HTTP code 200.
        * If the product uses the identifier type transmitted in the request but has no data to respond with, it should respond with HTTP code 204
        * If the product does not use the identifier type transmitted in the request, it should respond with HTTP code 209.

      parameters:
        - $ref: "#/components/parameters/prisonReferenceNumber"
        - $ref: "#/components/parameters/fromDate"
        - $ref: "#/components/parameters/toDate"
      responses:
        '200':
          $ref: '#/components/responses/ContentFound'
        '204':
          description: Request successfully processed - no content found
        '209':
          description: Subject Identifier is not recognised by this service
        '400':
          $ref: '#/components/responses/IncorrectRequest'
        '401':
          $ref: '#/components/responses/Unauthorised'
servers:
- url: https://complexity-of-need-staging.hmpps.service.justice.gov.uk
  description: Staging/dev environment
- url: https://complexity-of-need-preprod.hmpps.service.justice.gov.uk
  description: Pre-production environment
- url: https://complexity-of-need.hmpps.service.justice.gov.uk
  description: Production environment