feat: add REST documentation for fields query string parameters to filter response fields

Author: IgnatG

.editorconfig

@@ -10,6 +10,7 @@ end_of_line = lf
 insert_final_newline = true
 trim_trailing_whitespace = true
 charset = utf-8
+quote_type = single
 
 [*.js]
-max_line_length = 88
+max_line_length = 88

docs/api-guidelines/pagination-filtering-sorting.md

@@ -233,3 +233,93 @@ components:
           value: nhsNumber|asc,type|desc
           summary: Sort by multiple fields
 ```
+
+## Field Selection
+
+**SHOULD** support a `fields` query parameter to allow clients to specify which fields should be included in the JSON response.
+
+This improves performance by reducing payload size and network transfer time, and enhances usability for consumers who don't need the full object representation.
+
+### Query Parameter
+
+- `fields`: A comma-separated list of field names to include in the response.
+
+### Examples
+
+#### Basic field selection
+
+```text
+GET /api/widgets?fields=id,name,createdAt
+```
+
+Returns only the specified fields:
+
+```json
+{
+  "results": [
+    {
+      "id": "de750613-ef3c-4f5d-8148-10308b91896c",
+      "name": "Widget Example",
+      "createdAt": "2024-01-15T10:30:00Z"
+    }
+  ]
+}
+```
+
+#### Combining with other parameters
+
+```text
+GET /api/widgets?fields=id,name,status&status=active&limit=5
+```
+
+#### All fields (default behavior)
+
+When the `fields` parameter is omitted, all fields are returned:
+
+```text
+GET /api/widgets
+```
+
+### Behavior
+
+**SHOULD** implement the following behavior for the `fields` parameter:
+
+- **Valid fields**: Include only the requested fields in the response
+- **Invalid field names**: Ignore invalid field names silently and include only valid ones
+- **Empty fields parameter**: Return all fields (same as omitting the parameter)
+- **Case sensitivity**: Field names should be case-sensitive
+- **Nested fields**: Support dot notation for nested objects (e.g., `metadata.total`)
+
+```yaml
+components:
+  parameters:
+    fieldsParam:
+      in: query
+      name: fields
+      required: false
+      description: |
+        Comma-separated list of fields to include in the response.
+
+        Behaviour:
+        - Valid fields: include only the requested fields in the response.
+        - Invalid field names: ignore silently and include only valid ones.
+        - Empty fields parameter: return all fields (same as omitting the parameter).
+        - Case sensitivity: field names are case-sensitive.
+        - Nested fields: support dot notation for nested objects (e.g., `metadata.total`).
+      schema:
+        type: string
+        pattern: ^[a-z][a-z0-9]*(?:[A-Z0-9](?:[a-z0-9]+|$))*(?:\.[a-z][a-z0-9]*(?:[A-Z0-9](?:[a-z0-9]+|$))*)*(?:,[a-z][a-z0-9]*(?:[A-Z0-9](?:[a-z0-9]+|$))*(?:\.[a-z][a-z0-9]*(?:[A-Z0-9](?:[a-z0-9]+|$))*)*)*$
+      examples:
+        basicFields:
+          value: id,name,createdAt
+          summary: Basic field selection
+        nestedFields:
+          value: id,name,metadata.createdAt
+          summary: Including nested fields
+        withInvalidFields:
+          summary: Invalid fields are ignored
+          value: id,name,doesNotExist,metadata.total
+        emptyValueMeansAll:
+          summary: Empty value returns all fields
+          value: ""
+```

example/example.1.0.0.oas.yml

@@ -58,6 +58,7 @@ paths:
         - $ref: '#/components/parameters/limitParam'
         - $ref: '#/components/parameters/offsetParam'
         - $ref: '#/components/parameters/sortParam'
+        - $ref: '#/components/parameters/fieldsParam'
         - in: query
           name: type
           required: false
@@ -200,7 +201,7 @@ components:
           scopes:
             tests:read: read test results
             tests:write: submit test results
-  
+
   schemas:
     ResultRequest:
       type: object
@@ -465,6 +466,24 @@ components:
           value: nhsNumber|asc,type|desc
           summary: Sort by multiple fields
 
+    fieldsParam:
+      in: query
+      name: fields
+      description: Comma-separated list of fields to include in the response.
+      schema:
+        type: string
+        pattern: ^[a-z][a-z0-9]*(?:[A-Z0-9](?:[a-z0-9]+|$))*(?:\.[a-z][a-z0-9]*(?:[A-Z0-9](?:[a-z0-9]+|$))*)*(?:,[a-z][a-z0-9]*(?:[A-Z0-9](?:[a-z0-9]+|$))*(?:\.[a-z][a-z0-9]*(?:[A-Z0-9](?:[a-z0-9]+|$))*)*)*$
+      examples:
+        basicFields:
+          value: resultId,nhsNumber,result
+          summary: Basic field selection
+        nestedFields:
+          value: resultId,nhsNumber,metadata.createdAt
+          summary: Including nested fields
+        allFields:
+          value: resultId,nhsNumber,type,result,metadata.createdAt,metadata.updatedAt
+          summary: Multiple fields selection
+
   headers:
     Location:
       description: The URL of the created test result.
@@ -588,4 +607,4 @@ components:
 security:
   - oAuth:
       - tests:read
-      - tests:write
+      - tests:write