General description of API

API Handbook

API is a set of functions that help understand how to interact with a program, including:

• Operation that can be performed

• Data received as input

• Data returned as output (data content or error message)

VSaaS product API is organized based on REST.

REST API handles almost all interactions between server and client applications (the server application provides access to its data to the client application through a specific URL).

The VMS product API has predictable URLs oriented towards resources, returns responses in JSON format, uses standard HTTP response codes, and authentication.

All requests must have the header: Accept: application/json

This is necessary for the backend to understand whether the client supports responses in JSON format. If this header is not included, errors will be returned as an HTML page.

Authentication

Authentication in the API is done through a bearer token. It needs to be sent in the Authorization header.

Example: Authorization: Bearer eyJ0eXAiSUzI1NiJ9.eyJhdWQi.MHbBUJNRGEl2giGXN3uE

Requests that require authentication but don't provide a token or provide an incorrect one will result in an error with status 401.

Multilingualism

VMS supports multilingualism (the Russian and English languages). To change the language of the received responses, such as errors or resources, the Hl header or the hl parameter in the request needs to be sent.

Example

In the header - Hl: en

In the GET parameter - http://localhost/api/v1/items?hl=en

Errors

VMS uses standard HTTP response codes to indicate the success or failure of an API request.

• Codes in the 2xx range indicate success.

• Codes in the 4xx range indicate an error in the request that failed considering the provided information (e.g., a mandatory parameter was not specified).

• Codes in the 5xx range indicate technical errors, mostly related to VSaaS servers (they are rarely encountered).

Example of a response with a 4xx status

{
    "message": "The given data was invalid.",
    "errors": {
        "title": [
            "The title field is required."
        ]
    }
}

List of HTTP codes and their meanings

Pagination

All API resources support bulk retrieval using the list API methods. These API methods have a common structure, accepting at least two parameters: page and per_page.

{
    "data": [
        {...}
    ],
    "links": {
        "first": "https://localhost/url?page=1",
        "last": "https://localhost/url?page=4",
        "prev": null,
        "next": "https://localhost/url?page=2"
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "to": 25,
        "last_page": 4,
        "path": "https://localhost/url",
        "per_page": 25,
        "total": 86
    }
}

Response format:

• data – an array of requested objects

• links (all links in this object contain data in the GET parameters that were sent for filtering/sorting on this request):

  • first – link to the first page

  • last – link to the last page

  • prev – link to the previous page

  • next – link to the next page

• meta:

  • current_page – current page number

  • from – number of the element from which this page starts

  • to – number of the element at which this page ends

  • last_page – last page number

  • path – URL of the request without any parameters

  • per_page – number of items per page

  • total – total number of items corresponding to the request