Cryos API documentation - Data Formats

The Cryos API ensures input validation and rejects requests that do not provide data in the correct formats, signaling an HTTP status code 400 - Bad Request.

Additionally, the API maintains consistency in delivering response data by adhering to specific data types. Currently, JSON is the sole supported content type. JSON objects, known for their inherent flexibility, are constrained to specific formats across the API to ensure uniformity.

Most of the values are of type string, but others are are of type boolean, dateTime, and double are also supported. Please see below table regarding further details and examples upon this.

Direct Data formats

Direct Data Formats are designed to handle data directly between machines. These languages are often called machine readable, as they tend to be dense and compact.
The three most common formats in this category are JSON, XML, and YAML which all are used in this platform.

JSON

JSON (Javascript object notion) is a very widely used format for handling client side scripting, and it is also the preferred way of showing data from API to the caller. At Cryos we send the response in JSON format for easy readability. JSON might not be as powerful as other choices, but it supports many features that make its adoption a powerful choice - hence the reason for showing data in JSON. Another key consideration is that JSON supports distinction between numbers, strings and booleans which XML lacks (See the example under XML section). The below example showcases how the deliverynote looks like in JSON

XML

XML (EXtensible Markup Language) holds significant advantages. Its widespread usage, with a vast install base, is one of its key strengths. However, this ubiquity can also be its downfall. XML's primary advantage lies in its comprehensive nature—it's essentially the "kitchen sink" of formats, incorporating a wide array of features.

Yet, this all-encompassing approach can also be its primary drawback. XML's tendency to include everything imaginable makes it bulky and sluggish. Moreover, its handling of certain computations, particularly in XML transformation, can be inefficient.

All API policies are written in XML with embedded C# code for increased logic.

  • Rate limit - limit amount of request to secure safe flow of request without overfloading the API's

  • IP filtering for unwanted visitors - also if we see any violation of the aggrement, we will block that IP address

  • CORS handling - this includes which operation should be allowed, what headers to be shown to you etc.

  • Encryption of API keys and secrets

YAML

YAML, short for "YAML Ain’t Markup Language," serves as a human-friendly data serialization standard applicable across all programming languages. Unlike JSON, which lightweight characteristics but offers a somewhat limited feature set, and XML, known for its verbosity and occasional unwieldiness, YAML strikes a balance. It stands out for its readability, lightweight nature, and a generally moderate approach.

While it's primarily categorized as a direct data format due to its prevalent usage in parsing configuration settings and relational queries, numerous systems leverage YAML as a fundamental flat database.

Below is a snippet of the YAML file for the DeliveryNote API definition file, which can be downloaded from the API details page itself.