Cryos API documentation - Request and responses
This section provides guidelines for performing simple request/response operations on the three different Cryos APIs.
The easiest way to request data is by using the online test tool under the API section. Please the documentation on each APIs page regarding how to enter values correctly to the parameters. Watch the video below to get a sense of how to request data from the Donor API - note this is test data and not real data.
The Parameters are not the same for each API, but for all it is Odata parameters for filtering, selecting etc. If you as the EMR vendor believes that is too little, then reach out to us and we can have a discussion on which missing Odata parameters you need.
Request Headers
When you are requesting data with the APIs - you will see 2 different headers as a minimum, which is visible for all API's.
1. Cache-control header - set to no-cache as standard.
2. Ocp-Apim-Subscription-Key - this is your subscription key which it takes from the user itself, by default it takes the primary key unless you change it from the dropdown menu in the top. Do you use Postman, then remember to define this header paramter, otherwise you will recieve an error.
For the deiiveryNote there is an extra header - this is the API key or the clinic key which you need send from the clinic itself, without it, you are not getting any data.
NB: If you are not in the possession of the API key, please reach out to the API platform team at [email protected] and we will generate one for you. Please inform which clinic the API/Clinic key is to be generated for, and which EMR system they are using.
HTTP response headers
The current APIs exposed will have some pre defined HTTP response headers with different purposes. Some of these headers are for pure information for you as a user, for better understanding what is going on when requesting data (simply put, API design). Other HTTP request headers has been implemented for better support from the API team at cryos, in case errors should arise. The HTTP request headers are explained below.
Content-Encoding
The content-encoding will be displayed as 'content-encoding: gzip,' helping you save bandwidth efficiently by ensuring the proper compression of selected responses in outbound API traffic.
Content-Type
The content-type informs you about how the response is being delivered, and in the case of the Cryos API, it is in JSON format. For the endpoints that generate PDF files the content type would be Application/PDF
x-correlation-Id
The x-correlation-id is used for supporting the caller. You as a caller can't use it for any good, except when you encounter some issue and that issue keeps coming. Lets say you are requesting some donor data - but you keep getting an error, could be 401, 400, 500 etc. then we at Cryos can with the x-correlation-Id look that up in the backend and see what is going on - what Operation did you use, what parameter, error codes etc. please follow the requesting support section for how to request support.
x-ms-request-id
This Id is used for support if requests keeps failing - If a request is consistently failing, and you have verified that the request is properly formulated, we can use this value to report the error to Microsoft.
x-ratelimit-limit
This header is for the user only - it will show how many request the user has available. There is a limit of 24 calls per minute, and a renewel period of 60 seconds.
x-duration-seconds
The x-duration-seconds gives a time indication of how long the request takes.
x-ratelimit-remaining
Each time a user makes a request the ratelimit remaining will decrease.
x-request-context-data
The x-request-context-data header consist of multiple informative information for the requester such as the UserId, what region you are requesting from, and also what your IP-address is. The meaning of providing these information to you is to better help you if you encounter any errors. These headers will also be send to our application insights.
Query Options
There are different ways of querying for data in your request, and these APIs use OData (Open Data Protocol), which is the most preferable way of delivering/requesting data or filtering data.
On each operation, there is a detailed list of the OData parameters you can use, along with examples so you know how to request data. If you encounter any problems, issues, or find yourself stuck, you are always welcome to contact us.
Responses
The responses are straight forward, when you request data the response shows as Json data in the same section. The API response will only be shown in Json if the content-type is set to application/json, otherwise it will be what the content-type os set to. The endpoint that retrieves SOR reports for donors from single donor lookup or from the deliveryNote has the content-type set to application/pdf, and therefore no json data will be generated.
You as a user of the Cryos API platform are free to choose whether to choose the online tool for requesting data directly from the platform, or from your own test system/local environment. We know that the majority of the EMR vendors have their own environment set up to their settings, and there you are most comfatable using that. This platform is also design with the intention of testing the Request/Respsonse process of the APIs.
If you are interested we have also created some tutorials on how to quickly set a local environment using visual studio - this shows how to establish a connection to the API platform, and to retrieve data and start testing. Besides visual studio, we also have a tutorial on how to start using Postman for testing the APIs.