Fix broken JSON-in-Markdown

MDX struggled to parse the deeply (and inconsisently) indented code blocks, so this change replaces them for fenced code blocks which explictly mark them as JSON to allow syntax highlighting

Author: spikeheap

docs/api-specifications/index.md docs/api-specifications/README.mddocs/api-specifications/index.md renamed to docs/api-specifications/README.md

@@ -1,3 +1,6 @@
+---
+sidebar_position: 0
+---
 # Introduction
 
 As we continue to build on the number of APIs currently in service we provide a central repository for all of the specificactions that have been agreed.  The Swagger documentation provides a concise view of the various endpoints of our APIs and how to use them.  Our API specifications document our journey to establishing how the APIs were designed and the many decisions that were taken.  This will give us the opportunity to learn from our past choices and continue to build and improve as we go.

docs/api-specifications/accounts-api.md

@@ -29,7 +29,7 @@ A decoupled architecture that allows this entity to be reused across multiple se
 Accounts workshop - https://ideaflip.com/b/75dgi3rx6h2t/
 
 ## Endpoints to be created
-1. GET **//accounts?targetId={targetId}&type={accountType}**
+1. GET **//accounts?targetId=[targetId]&type=[accountType]**
 
     **Function:** Gets a collection of accounts for a person or organisation
 
@@ -75,7 +75,7 @@ Accounts workshop - https://ideaflip.com/b/75dgi3rx6h2t/
     ]
     ```
 
-2. GET **/accounts/arrears?type={accountType}&sort={propertyName}&direction={asc/desc}&resultsCount=[number of items]**
+2. GET **/accounts/arrears?type=[accountType]&sort=[propertyName]&direction=[asc/desc]&resultsCount=[number of items]**
 
     **Function:** Gets a collection of accounts that are in arrears
 
@@ -121,7 +121,7 @@ Accounts workshop - https://ideaflip.com/b/75dgi3rx6h2t/
     ]
     ```
 
-3. GET **/accounts/{id}**
+3. GET **/accounts/[id]**
 
     **Function:** Gets a single account record from the supplied id
 
@@ -196,7 +196,7 @@ Accounts workshop - https://ideaflip.com/b/75dgi3rx6h2t/
     }
     ```
 
-5. PATCH **/accounts/{id}**
+5. PATCH **/accounts/[id]**
 
     **Function:** Updates a person’s account details
 

docs/api-specifications/activities_api.md

@@ -131,35 +131,37 @@ Internal Server Error
 
 ## Example Payload
 
-          {
-          "id": "6f22e9ae3e8a4e0eaf46db02eb87f8e6",
-          "type": "create|update",
-          "target type": "person|asset|tenure....",
-          "target id": "TWVoZGlLaW1ha2hlCg==",
-          "datetime": "2021-02-19 15:12:00",
-          "time to live for the record": “365 days”,
-
-          //if we want to store data
-          "old data": {
-          "id": "TWVoZGlLaW1ha2hlCg==",
-          "title": "Mr",
-          "forename": "M",
-          "middle name": "",
-          "surname": "K",
-          ...
-          },
-          "new data": {
-          "id": "TWVoZGlLaW1ha2hlCg==",
-          "title": "Mr",
-          "forename": "Mehdi",
-          "middle name": "",
-          "surname": "Kimakhe",
-          ...
-          },
-
-          	"Author": {
-          "id": "TWVoZGlLaW1ha2hlCg==",
-          "full name": "Mehdi Kimakhe",
-          "email": "[email protected]"
-          }
-          }
+```json
+{
+  "id": "6f22e9ae3e8a4e0eaf46db02eb87f8e6",
+  "type": "create|update",
+  "target type": "person|asset|tenure....",
+  "target id": "TWVoZGlLaW1ha2hlCg==",
+  "datetime": "2021-02-19 15:12:00",
+  "time to live for the record": “365 days”,
+
+  //if we want to store data
+  "old data": {
+    "id": "TWVoZGlLaW1ha2hlCg==",
+    "title": "Mr",
+    "forename": "M",
+    "middle name": "",
+    "surname": "K",
+    ...
+  },
+  "new data": {
+    "id": "TWVoZGlLaW1ha2hlCg==",
+    "title": "Mr",
+    "forename": "Mehdi",
+    "middle name": "",
+    "surname": "Kimakhe",
+    ...
+  },
+
+  "Author": {
+    "id": "TWVoZGlLaW1ha2hlCg==",
+    "full name": "Mehdi Kimakhe",
+    "email": "[email protected]"
+  }
+}
+```

docs/api-specifications/asset_info.md

@@ -142,8 +142,8 @@ Below is the proposal link to all the new fields.
 Endpoint URLs:
 
        /assets
-       /assets/{prop-ref}
-       /assets?llpg-ref={llpg-ref}
+       /assets/[prop-ref]
+       /assets?llpg-ref=[llpg-ref]
        /assets/?postcode=E8 1DY
 
        Method: GET (list, search, view)
@@ -370,7 +370,7 @@ Internal Server Error
 3. ** Put Properties **
 ** Purpose: ** Update a particular asset
 
-Endpoint URL: asset/{id}
+Endpoint URL: asset/[id]
 
 Method: Put
 Request put object:
@@ -385,17 +385,19 @@ Asset Updated
 404
 Not found
 
-       {
-       "DevErrorMessages  ": ["validation errors"],
-       "UserErrorMessage": "Your item could not be updated for the following
-              reasons..."
-       }
+```json
+{
+  "DevErrorMessages  ": ["validation errors"],
+  "UserErrorMessage": "Your item could not be updated for the following
+        reasons..."
+}
+``
 500
 
        Internal Server Error
 
 
-4. PATCH properties `/assets/{id}`
+4. PATCH properties `/assets/[id]`
 
        ** Purpose: ** Updates an existing asset in dynamoDB database.
        We are using patch to allow for in place editing (single field updates).

docs/api-specifications/configuration.md

@@ -44,42 +44,44 @@ Used to retrieve a list of configurations
 
 ## Example Payload:
 
-                        [
-                          {
-                            "Type": "Person",
-                            "Configuration": {
-                              "ApiUrl": "http://www.hackney.gov.uk/person"
-                            },
-                            "FeatureToggles": {
-                              "CreatePerson": true,
-                              "EditPerson": false
-                            }
-                          },
-                          {
-                            "Type": "ContactDetails",
-                            "Configuration": {
-                              "ApiUrl": "http://www.hackney.gov.uk/contactdetails"
-                            },
-                            "FeatureToggles": {
-                              "AddContactDetails": true
-                            }
-                          },
-                          {
-                            "Type": "Tenure",
-                            "Configuration": {
-                              "ApiUrl": "http://www.hackney.gov.uk/tenure"
-                            },
-                            "FeatureToggles": {
-                              "CreateTenure": true
-                            }
-                          },
-                          {
-                            "Domain": "Asset",
-                            "Configuration": {
-                              "ApiUrl": "http://www.hackney.gov.uk/asset"
-                            },
-                            "FeatureToggles": {
-                              "ViewAsset": false
-                            }
-                          }
-                        ]
+```json
+[
+  {
+    "Type": "Person",
+    "Configuration": {
+      "ApiUrl": "http://www.hackney.gov.uk/person"
+    },
+    "FeatureToggles": {
+      "CreatePerson": true,
+      "EditPerson": false
+    }
+  },
+  {
+    "Type": "ContactDetails",
+    "Configuration": {
+      "ApiUrl": "http://www.hackney.gov.uk/contactdetails"
+    },
+    "FeatureToggles": {
+      "AddContactDetails": true
+    }
+  },
+  {
+    "Type": "Tenure",
+    "Configuration": {
+      "ApiUrl": "http://www.hackney.gov.uk/tenure"
+    },
+    "FeatureToggles": {
+      "CreateTenure": true
+    }
+  },
+  {
+    "Domain": "Asset",
+    "Configuration": {
+      "ApiUrl": "http://www.hackney.gov.uk/asset"
+    },
+    "FeatureToggles": {
+      "ViewAsset": false
+    }
+  }
+]
+```

docs/api-specifications/contact_details.md

@@ -49,11 +49,11 @@ https://ideaflip.com/b/bk558iy45tyt/
 - Forwarding addresses for future correspondence
 - Email address(es) for informed communication.
 - Endpoints to be created
-- GET /contact-details/{id} //will we ever have a use case to retrieve a single contact details record?
-- GET /contact-details?targetId={id}&includeHistoric=true //id of person/organization to retrieve all contact details, with optional filtering of whether historic details should be included. Default should be false.
+- GET /contact-details/[id] //will we ever have a use case to retrieve a single contact details record?
+- GET /contact-details?targetId=[id]&includeHistoric=true //id of person/organization to retrieve all contact details, with optional filtering of whether historic details should be included. Default should be false.
 - POST /contact-details
 - Inserts a new contact details record
-- PUT /contact-details/{id}
+- PUT /contact-details/[id]
 - Updates a contact details record.
 - In previous use cases, value of record was not updated - e.g. if a new phone number is created, a new record was added and old record was marked as inactive if applicable
 - Fields that should be updatable -

docs/api-specifications/contracts_api.md

@@ -34,7 +34,8 @@ Gets one or more Contracts from the Contract table.  Requests can be made by spe
 
 **Response:**
 - 200 OK
-```
+
+```json
 {
 	"results": [
 		{
@@ -218,7 +219,7 @@ Gets one or more Contracts from the Contract table.  Requests can be made by spe
 	}
 }
 ```
-- /contracts/{contractId}
+- /contracts/[contractId]
 
  Get individual contract
 
@@ -371,7 +372,7 @@ Create a new Contract
 Updates a Contract
 
 **Endpoint URL's:**
-/contracts/{contractId}
+/contracts/[contractId]
 
 **Request object:**
 ```
@@ -420,7 +421,7 @@ Updates a Contract
 Updates a new Contract
 
 **Endpoint URL's:**
-- /contracts/{contractId}
+- /contracts/[contractId]
 
 ### DELETE Contracts:
 
@@ -430,4 +431,4 @@ Updates a new Contract
 Removes a new Contract
 
 **Endpoint URL's:**
-- /contracts/{contractId}
+- /contracts/[contractId]

docs/api-specifications/equality-information-api.md

@@ -57,10 +57,10 @@ In the second workshop, we discussed the necessity of the equalities information
 
 ### Endpoints to be created for the equality information microservice
 
-1. GET **/equality-information/{equality-information-id}**
-2. GET **/equality-information/{target-id}**
-3. PATCH **/equality-information/{equality-information-id}**
-4. POST **/equality-information/{equality-information-id}**
+1. GET **/equality-information/[equality-information-id]**
+2. GET **/equality-information/[target-id]**
+3. PATCH **/equality-information/[equality-information-id]**
+4. POST **/equality-information/[equality-information-id]**
 
 **Example payload**
 ```

docs/api-specifications/notes.md

@@ -78,11 +78,12 @@ https://ideaflip.com/edit/uhe2bvdkm8fj/3TqQ2hqBlWef
 404
 If item was not found
 
-                {
-                  “devErrorMessages”: [“debug info or stack trace”],
-                  “userErrorMessage”: “The item you search for was not found”
-                }
-
+```json
+{
+  “devErrorMessages”: [“debug info or stack trace”],
+  “userErrorMessage”: “The item you search for was not found”
+}
+```
 
 ** Post Note **
 Purpose: Creates one or more notes.
@@ -110,7 +111,7 @@ Internal Server Error
 ** Put Note **
 ** Purpose: ** Update a particular note
 
-Endpoint URL: notes/{id}
+Endpoint URL: notes/[id]
 
 Method: Put
 Request put object:
@@ -133,7 +134,7 @@ Internal Server Error
 ** Delete Note **
 ** Purpose: ** Delete a particular note
 
-Endpoint URL: notes/{id}
+Endpoint URL: notes/[id]
 
 Method: Delete
 

docs/api-specifications/notificationss-api.md

@@ -133,7 +133,7 @@ I can take necessary action
         }
     ]
     ```
-3. GET **/message-status/{service}/{notificationId}**
+3. GET **/message-status/[service]/[notificationId]**
     **Function:** Gets the status of a message sent within the retention period (7 days)
     **Response Payload**
     ```
@@ -165,7 +165,7 @@ I can take necessary action
     }
     ```
 
-5. PATCH **/notifications/{id}**
+5. PATCH **/notifications/[id]**
     **Function:** Updates the action details of a notification
     **Request Payload:**
     ```
@@ -175,7 +175,7 @@ I can take necessary action
         “actionNote”:””
     }
     ```
-6. DELETE **/notifications/{id}**
+6. DELETE **/notifications/[id]**
     **Function:** Deletes the specified notification
 
 ## Other considerations