mesh-1116: review tweaks, normalise single quotes , remove tabs add versioning

matt-mercer · matt-mercer · commit 211ee6910318 · 2023-02-27T12:38:56.000Z
diff --git a/specification/mesh-api.yaml b/specification/mesh-api.yaml
@@ -13,14 +13,14 @@ info:
     - send a message, or a larger message as series of chunks
     - download a message, or a larger message which was sent to you as a series of chunks
     - acknowledge the successful download of a message, which removes it from your inbox
-    - get the messageIds of messages in your inbox that are ready for download
+    - get the identifiers of messages in your inbox that are ready for download
     - track the status of messages that you sent from your outbox
     - look up the mailbox of an organisation you want to send data to
     - validate your mailbox every 24 hours to let Spine know it's still active
 
     ## Who can use this API
 
-    This API can only be used where there is a legal basis to do so. We’ll ask you to demonstrate this as part of the digital onboarding process before your software goes live.
+    This API can only be used where there is a legal basis to do so. We'll ask you to demonstrate this as part of the digital onboarding process before your software goes live.
 
     ## Requirements for using this API
     There are 2 parts to getting the MESH API, these are:
@@ -30,15 +30,15 @@ info:
 
     ### 1. Developing and integrating your software
 
-    You’ll need some things at different stages of your development to integrate with the MESH API.
+    You'll need some things at different stages of your development to integrate with the MESH API.
     For each environment you use, you'll need a:
     - MESH mailbox ID and password
     - Transport Layer Security (TLS) certificate
     - shared secret to include in the MESH authorization header
     
     ### 2. Getting your software approved to go live
     
-    This is also called digital onboarding. You’ll need to submit information that demonstrates:
+    This is also called digital onboarding. You'll need to submit information that demonstrates:
     - you have a valid use case
     - you can manage risks
     - your software conforms technically with the requirements for this API
@@ -51,17 +51,21 @@ info:
     - completing onboarding processes and waiting for approval
     
     You can do some things while you wait, but expect the end-to-end integration process to take 1 month or more.
+    
+    ### Versioning
+  
+    MESH API now has BETA support for versioning on certain endpoints in order to allow us to safely make new features and capabilities available to API consumers. For information on how to call a versioned API endpoint see [API Versioning](#section/API-Versioning).
 
     ### Get started
     
     To get started, sign in or create a developer account for digital onboarding, complete the 'Setup and eligibility' section and submit it.
 
-    If you’re new to digital onboarding, add your product and select ‘MESH’ from the ‘APIs to be used’ list.
-    Submitting this information shows us that you have a legal basis to use the MESH API. We’ll review the information you submit and respond within 5 to 10 working days.
+    If you're new to digital onboarding, add your product and select 'MESH' from the 'APIs to be used' list.
+    Submitting this information shows us that you have a legal basis to use the MESH API. We'll review the information you submit and respond within 5 to 10 working days.
 
-    If we approve your request to use the MESH API, we’ll also email you a supplier pack within 10 working days. Read through this as it contains the testing requirements you’ll need to fulfil later on.
+    If we approve your request to use the MESH API, we'll also email you a supplier pack within 10 working days. Read through this as it contains the testing requirements you'll need to fulfil later on.
 
-    You should get your use case approved before you go too far with development. You can choose to proceed with your integration while you wait for approval, but you’ll be doing this at your own risk.
+    You should get your use case approved before you go too far with development. You can choose to proceed with your integration while you wait for approval, but you'll be doing this at your own risk.
     
      [Sign in or create a developer account for digital onboarding](https://onboarding.prod.api.platform.nhs.uk)
     
@@ -72,44 +76,44 @@ info:
 
     ### Request a mailbox
 
-    Once we’ve approved your request to use the MESH API, you’ll need to request a MESH Mailbox to use in a 'Path to Live integration environment'. This is how you’ll interact with the MESH API. A MESH Mailbox is secure and only your organisation can access it.
+    Once we've approved your request to use the MESH API, you'll need to request a MESH Mailbox to use in a 'Path to Live integration environment'. This is how you'll interact with the MESH API. A MESH Mailbox is secure and only your organisation can access it.
 
-    To request a MESH Mailbox, you’ll need to fill in an online form. It takes 5 to 10 minutes to complete.
+    To request a MESH Mailbox, you'll need to fill in an online form. It takes 5 to 10 minutes to complete.
 
-    You’ll need to know:
+    You'll need to know:
     - your [ODS code](https://odsportal.digital.nhs.uk/)
     - the [workflow groups or IDs](https://digital.nhs.uk/services/message-exchange-for-social-care-and-health-mesh/workflow-groups-and-workflow-ids) for the files you plan to send or receive
     - the contact details of the person who will be managing the mailbox in your organisation
     
     [Request a 'Path to Live integration' MESH Mailbox](https://digital.nhs.uk/services/message-exchange-for-social-care-and-health-mesh/messaging-exchange-for-social-care-and-health-apply-for-a-mailbox)
     
-    ### Receive your credentials for the ‘Path to Live integration’ environment
+    ### Receive your credentials for the 'Path to Live integration' environment
 
-    Once you’ve requested a MESH Mailbox, we’ll send you an email containing your Mailbox ID and password within 5 working days. Keep these details safe as we’ll also ask you for this if you need help from our support teams.
+    Once you've requested a MESH Mailbox, we will email you your Mailbox ID and password within 5 working days. Keep these details safe as we'll also ask you for this if you need help from our support teams.
 
-    You will also receive the shared secret. You’ll need to include this in the [MESH authorization header](https://digital.nhs.uk/developer/api-catalogue/message-exchange-for-social-care-and-health-api#api-description__mesh-authorization-header) when you develop this part of your software.
+    You will also receive the shared secret. You'll need to include this in the [MESH authorization header](https://digital.nhs.uk/developer/api-catalogue/message-exchange-for-social-care-and-health-api#api-description__mesh-authorization-header) when you develop this part of your software.
     
     ### Get a TLS certificate
 
-    You’ll need a TLS certificate to establish a secure connection to MESH.
+    You'll need a TLS certificate to establish a secure connection to MESH.
     
     How to get a TLS certificate
     
-    1.	Generate a private key using your preferred method, with the naming convention cn=mailboxid.odscode.api.mesh-client.nhs.uk
-    2.	Generate a certificate signing request (CSR) based on the private key and your Mailbox ID.
-    3.	Email the CSR to [itoc.supportdesk@nhs.net](mailto:itoc.supportdesk@nhs.net) - this needs to contain the common name from your CSR 'Subject' using the format local_id.ods_code.api.mesh-client.nhs.uk
+    1. Generate a private key using your preferred method, with the naming convention cn=mailboxid.odscode.api.mesh-client.nhs.uk
+    2. Generate a certificate signing request (CSR) based on the private key and your Mailbox ID.
+    3. Email the CSR to [itoc.supportdesk@nhs.net](mailto:itoc.supportdesk@nhs.net) - this needs to contain the common name from your CSR 'Subject' using the format local_id.ods_code.api.mesh-client.nhs.uk
 
     The local_id is a local identifier such as a server name and ods_code is your ODS code, for example, SERVER001.X26.api.mesh-client.nhs.uk.
 
-    Once we receive your CSR, we’ll send you a TLS certificate within 5 working days.
+    Once we receive your CSR, we'll send you a TLS certificate within 5 working days.
 
     Depending on how you implement MESH API, you may also need to [download a RootCA and SubCA certificate](https://digital.nhs.uk/services/path-to-live-environments/integration-environment#rootca-and-subca-certificates). These are also required to establish a secure connection.
 
     ### Develop and test your software
     
     Now that you have a MESH Mailbox for a 'Path to Live integration' environment and a TLS certificate, start developing your software using the MESH API.
     
-    When you’re ready to go live, you’ll need to:
+    When you're ready to go live, you'll need to:
     - request a TLS certificate for the production environment
     - request a MESH mailbox for the production environment
     - get a conformance certificate
@@ -124,60 +128,60 @@ info:
     
     This shows that your software meets our non-functional requirements.
     
-    [Sign into digital onboarding to answer questions on 'non-functional'requirements](https://identity.prod.api.platform.nhs.uk/auth/realms/developer-identity/login-actions/authenticate?client_id=digital-onboarding-service&tab_id=YTe9EqJeUCc) 
+    [Sign in to the digital onboarding to answer questions on 'non-functional' requirements](https://identity.prod.api.platform.nhs.uk/auth/realms/developer-identity/login-actions/authenticate?client_id=digital-onboarding-service&tab_id=YTe9EqJeUCc) 
 
     ### Demonstrate technical conformance
 
-    Before you can go live, in digital onboarding, you’ll need to:
+    Before you can go live, in digital onboarding, you'll need to:
     - answer some questions to show you conform to the technical requirements of our APIs
     - upload a conformance certificate
 
-    To get a technical conformance certificate, you’ll need to complete the testing requirements in the supplier pack we sent to you.
+    To get a technical conformance certificate, you'll need to complete the testing requirements in the supplier pack we sent to you.
 
     Some of these tests have to be witnessed by us. To arrange a witness test, reply to the email that contains the supplier pack. The witness testing takes 2 to 3 hours.
 
     In some cases, we may ask you to prepare test data a few days before the day of the witness testing.
 
-    When you’ve completed a witness test, we’ll email a technical conformance certificate to you within 5 working days. You can then upload it to digital onboarding.
+    When you've completed a witness test, we'll email a technical conformance certificate to you within 5 working days. You can then upload it to digital onboarding.
     
-    [Sign into digital onboarding to upload a technical conformance certificate](https://identity.prod.api.platform.nhs.uk/auth/realms/developer-identity/login-actions/authenticate?client_id=digital-onboarding-service&tab_id=vYrgcflr9fs)
+    [Sign in to the digital onboarding to upload a technical conformance certificate](https://identity.prod.api.platform.nhs.uk/auth/realms/developer-identity/login-actions/authenticate?client_id=digital-onboarding-service&tab_id=vYrgcflr9fs)
 
     ### Get a MESH Mailbox for your live software
 
-    When you’re ready to send or receive real data, you’ll need a MESH Mailbox in the production environment. We’ll ask to see the conformance certificate for your software before we issue this.
+    When you're ready to send or receive real data, you'll need a MESH Mailbox in the production environment. We'll ask to see the conformance certificate for your software before we issue this.
 
-    MESH Mailboxes are specific to environments, this means you’ll need a different MESH Mailbox ID for each environment you use.
+    MESH Mailboxes are specific to environments, this means you'll need a different MESH Mailbox ID for each environment you use.
 
-    To request a MESH Mailbox, you’ll need to fill in an online form. It takes 5 to 10 minutes to complete.
+    To request a MESH Mailbox, you'll need to fill in an online form. It takes 5 to 10 minutes to complete.
 
-    You’ll need to know:
-    -	your [ODS code](https://odsportal.digital.nhs.uk/)
+    You'll need to know:
+    - your [ODS code](https://odsportal.digital.nhs.uk/)
     - the [workflow groups or IDs](https://digital.nhs.uk/services/message-exchange-for-social-care-and-health-mesh/workflow-groups-and-workflow-ids) for the files you plan to send or receive
     - the contact details of the person who will be managing the mailbox in your organisation
 
-    [Request a ‘Live’ MESH Mailbox](https://digital.nhs.uk/services/message-exchange-for-social-care-and-health-mesh/messaging-exchange-for-social-care-and-health-apply-for-a-mailbox)
+    [Request a 'Live' MESH Mailbox](https://digital.nhs.uk/services/message-exchange-for-social-care-and-health-mesh/messaging-exchange-for-social-care-and-health-apply-for-a-mailbox)
     
     ### Get a TLS certificate for the production environment
 
-    Once you have a Mailbox ID, you’ll need to get a TLS certificate. This allows you to establish a secure connection to MESH in the production environment.
+    Once you have a Mailbox ID, you'll need to get a TLS certificate. This allows you to establish a secure connection to MESH in the production environment.
 
     How to get a TLS certificate
-    1.	Generate a private key using your preferred method, with the naming convention cn=mailboxid.odscode.api.mesh-client.nhs.uk
-    2.	Generate a CSR based on the private key and your Mailbox ID
-    3.	Email the CSR and technical conformance certificate to [ssd.nationalservicedesk@nhs.uk](mailto:ssd.nationalservicedesk@nhs.uk) - this needs to contain the common name from your CSR 'Subject' using the format local_id.ods_code.api.mesh-client.nhs.uk
+    1. Generate a private key using your preferred method, with the naming convention cn=mailboxid.odscode.api.mesh-client.nhs.uk
+    2. Generate a CSR based on the private key and your Mailbox ID
+    3. Email the CSR and technical conformance certificate to [ssd.nationalservicedesk@nhs.uk](mailto:ssd.nationalservicedesk@nhs.uk) - this needs to contain the common name from your CSR 'Subject' using the format local_id.ods_code.api.mesh-client.nhs.uk
 
     The local_id is a local identifier such as a server name and ods_code is your ODS code, for example, SERVER001.X26.api.mesh-client.nhs.uk.
 
-    Once we receive your CSR and technical conformance certificate, we’ll send you a TLS certificate for the production environment within 5 working days.
+    Once we receive your CSR and technical conformance certificate, we'll send you a TLS certificate for the production environment within 5 working days.
 
     Depending on how you implement MESH API, you may also need to [download a RootCA and SubCA certificate](https://digital.nhs.uk/services/path-to-live-environments/integration-environment#rootca-and-subca-certificates). These are also required to establish a secure connection.
 
 
     ### Sign connection agreement
 
-    You’ll need to sign a connection agreement before your software can go live. Once you’ve signed it, you need to upload it to the ‘Legal agreement’ section in digital onboarding. We’ll email your connection agreement to you within 5 working days of completing your witness test.
+    You'll need to sign a connection agreement before your software can go live. Once you've signed it, you need to upload it to the 'Legal agreement' section in digital onboarding. We'll email your connection agreement to you within 5 working days of completing your witness test.
 
-    [Sign into digital onboarding to upload your connection agreement](https://identity.prod.api.platform.nhs.uk/auth/realms/developer-identity/login-actions/authenticate?client_id=digital-onboarding-service&tab_id=p19cQckpJso)
+    [Sign in to the digital onboarding to upload your connection agreement](https://identity.prod.api.platform.nhs.uk/auth/realms/developer-identity/login-actions/authenticate?client_id=digital-onboarding-service&tab_id=p19cQckpJso)
 
     ### Go live with your software
 
@@ -229,6 +233,20 @@ info:
     There is a basic sandbox implementation of the MESH API available [mesh-sandbox](https://github.com/NHSDigital/mesh-sandbox).
 
     This sandbox can be used for local development and currently does not require a client certificate
+    
+    
+    ## API Versioning
+      
+    MESH uses the `Accept` header to support different versions in the same API, sending a different `Accept` header will vary the response, refer to individual API endpoints for more detail.
+    
+    If not specified `Accept: application/json` will be assumed and the lowest supported response version for that particular endpoint will be returned.
+      
+    **Note:** please refer to the table below for more detail on the status of a given API version.
+  
+    | Version | Accept                                               | Status    |
+    |---------|------------------------------------------------------|-----------|
+    | 1       | `application/json` or `application/vnd.mesh.v1+json` | live      |
+    | 2       | `application/vnd.mesh.v2+json`                       | live-beta |
 
     ## MESH Authorization header
     Requests to the MESH API require an authorisation token in the HTTP `Authorization` header.
@@ -382,7 +400,7 @@ info:
 
     ## Onboarding
     
-    You need to get your software approved by us before it can go live with this API. We call this onboarding. The onboarding process can sometimes be quite long, so it’s worth planning well ahead.
+    You need to get your software approved by us before it can go live with this API. We call this onboarding. The onboarding process can sometimes be quite long, so it's worth planning well ahead.
     
     To get started with the MESH API you will need to create a developer account. This is where you can demonstrate that you can manage risks and that your software conforms technically with the requirements for this API. You can also manage onboarding for other APIs in your account.
 
