docs: Added OpenAPI spec and API request collection

Author: alex-clayton-1

api/api-request-collection/servicelayer-api-2025-04-04.har

@@ -0,0 +1,59 @@
+{
+	"log": {
+		"version": "1.2",
+		"creator": {
+			"name": "Insomnia REST Client",
+			"version": "insomnia.desktop.app:v11.0.1"
+		},
+		"entries": [
+			{
+				"startedDateTime": "2025-04-04T09:29:36.496Z",
+				"time": 0,
+				"request": {
+					"method": "POST",
+					"url": "http://localhost:7001/api/bsselect/episodes/ingress",
+					"httpVersion": "HTTP/1.1",
+					"cookies": [],
+					"headers": [
+						{
+							"name": "Content-Type",
+							"value": "application/json"
+						}
+					],
+					"queryString": [],
+					"postData": {
+						"mimeType": "application/json",
+						"text": "{\n\t\"episode_id\": \"123\",\n\t\"nhs_number\": \"9990000000\",\n\t\"date_of_birth\": \"1970-01-01\",\n\t\"first_given_name\": \"Test\",\n\t\"family_name\": \"User\"\n}"
+					},
+					"headersSize": -1,
+					"bodySize": -1
+				},
+				"response": {
+					"status": 0,
+					"statusText": "",
+					"httpVersion": "HTTP/1.1",
+					"cookies": [],
+					"headers": [],
+					"content": {
+						"size": 0,
+						"mimeType": ""
+					},
+					"redirectURL": "",
+					"headersSize": -1,
+					"bodySize": -1
+				},
+				"cache": {},
+				"timings": {
+					"blocked": -1,
+					"dns": -1,
+					"connect": -1,
+					"send": 0,
+					"wait": 0,
+					"receive": 0,
+					"ssl": -1
+				},
+				"comment": "BS Select Episode Ingress"
+			}
+		]
+	}
+}

api/openapi/openapi.yaml

@@ -0,0 +1,68 @@
+openapi: 3.0.3
+info:
+  title: ServiceLayer API
+  version: 1.0.0
+  description: API used to ingest episodes from screening services into NSP
+
+paths:
+
+  /bsselect/episodes/ingress:
+    post:
+      summary: BS Select Episode Ingress
+      description: Validates the incoming BS Select episode and enqueues it for further processing within the NSP
+      operationId: BS Select Episode Ingress
+      tags:
+        - Episodes
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/BSSelectEpisode"
+      responses:
+        '200':
+          description: Episode accepted
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/BSSelectEpisode"
+        '400':
+          description: Bad request. Supplied episode payload invalid.
+          content:
+            text/plain:
+              schema:
+                type: string
+              example: "nhs_number is required"
+        '500':
+          description: Internal server error. This indicates an unexpected failure in the service.
+
+components:
+  schemas:
+    BSSelectEpisode:
+      type: object
+      required:
+        - episode_id
+        - nhs_number
+        - date_of_birth
+        - first_given_name
+        - family_name
+      properties:
+        episode_id:
+          type: string
+          description: Unique identifier for the Episode
+        nhs_number:
+          type: string
+          pattern: '^\d{10}$'
+          description: NHS Number (exactly 10 digits)
+        date_of_birth:
+          type: string
+          format: date
+          description: Date of birth of the Participant
+        first_given_name:
+          type: string
+          maxLength: 100
+          description: First name of the Participant
+        family_name:
+          type: string
+          maxLength: 100
+          description: Surname of the Participant