Standards and Conventions

Introduction

This article will present and describe principles, standards and conventions we apply to our APIs and processes. The following information may be subject to change and may as well not apply to other software.

We use OpenAPI 3 Standard for our Technical Documentation and Endpoints description. All Technical Documentation can be found in the Developer’s Portal. Moreover, all Crypto APIs are REST.

URI

URI Structure

The Crypto APIs and endpoint URIs follow the RFC 3986 specification and are divided into three main parts, applicable to all Crypto APIs products (Blockchain Events, Blockchain Data, etc.):

1. The domain and subdomain in the URI always display as: rest.cryptoapis.io
2. Next is displayed the version of the product, e.g. currently it is: /v2/
3. Next is displayed the product name, where words are separated with spinal-case: /blockchain-data/

Example:

rest.cryptoapis.io/v2/blockchain-data/..

Depending on which product is specified, after that the URI’s structure may look different in each case. The different Crypto APIs products require different query parameters and variables.

After the main URI parts, it is completed with a component and after that - parameters.

Example:

../address/${litecoinValidAddress}

URI Naming Standards

URIs have to follow the naming standards as listed below:

• the URI has to be written in all lower cases, except when a specific string requires capital letters;
• the path parameter must use spinal-case ( a hyphen - ) to separate words, e.g. /v2/blockchain-data;
• the query parameters must use camelCase to differentiate words, e.g. /v2/blockchain-data/bitcoin/addresses?offset=10&limit=0;
• the variables must use camelCase to differentiate words, e.g. /v2/blockchain-data/bitcoin/addresses/${bitcoinValidAddress};
• all URLs must be HTTPS - secured, using only HTTP is not accepted.

URI Maximum Length

The entire URI cannot exceed 2000 characters in length including any punctuation marks, e.g. commas, hyphens, question marks, pluses or forward slashes.

Request and Response Standards

Basic API Request

Main prerequisites for requests to the Crypto APIs include:

• requests are sent through HTTPS only to the domain rest.cryptoapis.io;
• headers must by default incorporate the JSON content type application/json;
• all custom for Crypto APIs attributes are indicated in the beginning with an x-, e.g. x-attribute;
• request public attributes must be all camelCase, e.g. "apiVersion": 2, "attributeName": "attributeValue";
• we enable CORS (Cross-Origin Resource Sharing), for which the API responds with an Access-Control-Allow-Origin: header. Nevertheless, your users shouldn’t make direct API requests from a web application that you are building, as our CORS policy may change at some point without warning and any such requests could be then rejected;
• no random unspecified keys can be added to the Crypto APIs URI, e.g. ?randomKey=randomUnspecifiedValue, as that will result in a 400 error;
• all requests to the Crypto APIs must be authenticated with an API key. Clients can generate API keys through their dedicated Dashboards only after product subscription. Multiple API keys can be generated for a single user. To see more information on Authentication, please see the respective article;
• API keys must be kept secure and private by the users who own them. API keys must not be uploaded to a frontend of a mobile or web application or in any open source code, as API keys represent access to the user’s account and the data inside.

Shortly put, all Crypto APIs requests include:

REST API Base URL: https://rest.cryptoapis.io
API Version: /v2/
Authentication (API Key + JSON)
Request Type (GET, POST, PUT, PATCH, DELETE)

Our API Requests incorporate the following HTTP methods:

POST requests always contain the following body structure:

{
    "apiVersion": "2.0", // The current API version.
    "context": "You can add any text here.", // Optional: In case you send this value in the request.
    "data": { // Contains the request parameters.
        "item": { // Single item’s details.
            "endpointAttribute": "value" // Parameter data.
        }
    }
}

If an endpoint has no parameters, the body structure has less data:

{
    "apiVersion": "2.0", // The current API version.
    "context": "You can add any text here", // Optional: In case you send this value in the request.
    "data": { // Contains the request parameters.
        "item": { } // Single item’s details.
    }
}

Basic API Response

Responses to Crypto APIs requests prerequisites:

• response public attributes must be all camelCase, e.g. ”apiVersion”: 2, ”customAttribute”: "customAttribute";
• Crypto APIs requests always return the following parameters:

{
 "apiVersion": "",
    "requestId": "",
    "context": "",
    "data": {
        "item": {
              }
    }
}

• apiVersion reflects the version of the software used, currently it is V2;
• requestId is a unique code used with the purposes of tracking, support, etc.;
• the attribute data always contains the result, no matter of the quantity of items in it;
• the attribute item specifies the response’s result indicating there is only a single one, when listed as items it means there are two or more results, i.e. a list of results, in the response;
• all calculated prices are always in USD currency;
• we use pagination methods to limit the results in the response, specifically on responses that can potentially return hundreds or thousands of results, please see more information in our Data Flow Limiting section.
• each response header contains the following keys, which define the user’s credit usage, to see more information on credits, please see our API Credential Use section:

“x-credits-consumed”
“x-credits-available”
“x-response-time”

The context parameter

The context parameter is an optional attribute created with the idea to facilitate users when they make requests in bulk.

They can set the context attribute as a string with simple text of their choosing. Afterwards each returned information will contain the specific context string of its associated request. Through this process users can keep track of the responses that come in.

For GET requests the attribute can be set as a query parameter. For POST requests it can be set as a query or body parameter. In the latter scenario there’s a safety measure embedded in case the user sets context as both a query and body parameter - the system will then take into account the body context attribute.

Error and HTTP Code Standards

The full list of Errors you can see on our respective page.

The errors we use follow the HTTP Error Codes Standard.

The structure of the error always returns the following values, as listed and described in the example:

Example:

{
    "apiVersion": "", // The current API Version.
    "requestId": "", // Each request has a unique ID, for which the Support team could ask for when contacted.
    "context": "", // Optional: In case you send this value in your request.
    "error": {
        "code": "", // Error Code, please check our [Errors page](https://developers.cryptoapis.io/technical-documentation/general-information/errors-and-api-statuserrors) to see the full list of error codes.
        "message": "", // Is the human readable error message.
        "details": "" // Optional: Some errors may need more details.
    }
}

Date and Time Formats

For all required endpoints that use a time parameter, the accepted value is timestamp which is always UTC-based by definition. The human date which corresponds to the timestamp is always converted by the system to UNIX Epoch time and returned as an integer.

Example:

Human time: 09:12:41 AM 28th January 2021

Which corresponds to:

UNIX Epoch time: 1611825161

Hence the system will return ”timestamp”: 1611825161 and not the human time.

The UNIX Epoch time is a system that describes a point in time. This would be the amount of time in seconds that have passed since the Unix Epoch which was 00:00:00 UTC on 1 January 1970, minus leap seconds.