Standards Conventions and Versioning

Standards and Conventions

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 Vaultody endpoints are REST.

Vaultody Versioning

An additional feature in the Vaultody system allows us to generate new API versions of our endpoints each time backwards-incompatible changes have been made to them. Versions are generally titled with a date and "stable" versions are marked as such. You can try out new features and changes in our newer versions not marked as "stable". Our technical documentation lists all available API versions. To view a specific one, select it from the drop down menu. All requests use your account's API version, unless you override the API version with a header.

URI

URI Structure

The Vaultdoy and endpoint URIs follow the RFC 3986 specification and are divided into two main parts, applicable to all Vaultody endpoints : The domain and subdomain in the URI always display as: **rest.vaultody.com

1. The domain and subdomain in the URI always display as: rest.vaultody.com
2. Next is displayed the product name, where words are separated with spinal-case: /vaults/

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. /vaults/;
• the query parameters must use camelCase to differentiate words, e.g. /vaults/bitcoin/addresses?offset=10&limit=0;
• the variables must use camelCase to differentiate words, e.g. /vaults/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 Vaultody APIs include:

• requests are sent through HTTPS only to the domain rest.vaultody.com;
• headers must by default incorporate the JSON content type application/json;
• all custom for Vaultody attributes are indicated in the beginning with an x-, e.g. x-attribute;
• request public attributes must be all camelCase, e.g. "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 Vaultdoy URI, e.g. ?randomKey=randomUnspecifiedValue, as that will result in a 400 error;
• all requests to the Vaultody must be authenticated with an API key. Owner can generate API keys through the dedicated Dashboards only after product subscription. Multiple API keys can be generated.
• 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 Vaultdoy API requests include:

REST API Base URL: https://rest.vaultody.com
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:

{
    "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:

{
    "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 Vaultody APIs requests prerequisites:

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

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

• 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.

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 page below contains a comprehensive compilation of errors.

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:

{
    "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.vaultody.com/technical-documentation/general-information) to see the full list of error codes.
        "message": "", // Is the human readable error message.
        "details": "" // Optional: Some errors may need more details.
    }
}

List of errors

All requests with a response status code different than 200 (successful HTTP) are considered as a failure of the particular API call and referred to as “HTTPS errors”. When the response (error) is returned an additional JSON is present in the body containing the error message. Depending on what has gone wrong with the API call, the error message is different.

As best practice we recommend to store all error messages somewhere along with request data for further manual review.

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.vaultody.com/technical-documentation/api/general-information) to see the full list of error codes.
        "message": "", // Is the human readable error message.
        "details": "" // Optional: Some errors may need more details.
    }
}

We use the following error codes:

General errors

Custom errors:

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.