-
Notifications
You must be signed in to change notification settings - Fork 1
/
Complexity Of Need API Specification.yaml
336 lines (327 loc) · 10.9 KB
/
Complexity Of Need API Specification.yaml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
---
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