General description of API

API general information

API (Application Programming Interface) is a set of rules, methods, and functions that enable different software applications to communicate with each other. An API defines how applications can request and receive data, as well as perform specific actions. It includes:

• Operations to be performed (methods): This refers to the set of actions or tasks that an application can carry out through the API.

• Input data (requests): This is the information that an application sends to the API to initiate a specific operation. It could be in the form of parameters, arguments, or data structures.

• Output data (responses): This is the information that the API sends back to the application in response to a request. This could be the requested data, a status indicating whether the operation was successful, or error messages if something went wrong.

The VSaaS product API is built on REST.

A REST API serves as the primary communication channel between server-side and client-side applications. The server-side application exposes its data to the client-side application via a specific URL.

API of the VMS product features the following:

• Authentication.

• Resource-oriented URLs. Uses predictable URLs that directly relate to the data being accessed.

• JSON responses.

• Employs standard HTTP status codes to indicate the success or failure of requests.

All requests should contain the following header: Content-Type: application/json.

This is necessary for the server (backend) to understand whether the client supports JSON-formatted responses. If this header is missing, the server might return a response in an incompatible format – errors could be returned as an HTML page.

Authentication

To carry out API requests, authentication is required.

Authentication is performed using a bearer token. It should be specified in the Authorization header.

Example: Authorization: Bearer eyJ0eXAiSUzI1NiJ9.eyJhdWQi.MHbBUJNRGEl2giGXN3uE

Requests will return a 401 Unauthorized error if authentication is required, but no valid token is provided.

Multilingual support

VMS allows you to customize the output language to your preference, either Russian or English.

To change the output language, such as error messages or resources, you must specify the language parameter hl either in the request header or in the query string.

Examples:

• In the header – Hl: en

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

Examples of responses

VMS employs standard HTTP status codes to indicate successful API requests or errors.

The HTTP status codes and definitions

A response example with a 4xx status:

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

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.

All API endpoints support bulk data retrieval through list methods. These API methods adhere to a standardized structure, mandating at least page and per_page parameters.

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

• data – an array of objects that match the query

• links – an object containing links for result pagination. Links within the links object are formed based on query parameters (filters and sorting):

  • first – URLs to go to the first page.

  • last – URLs to go to the last page.

  • prev – URLs to go to the previous page.

  • next – URLs to go to the next page.

• meta

  • current_page – the current page number.

  • from – the index of the first item on the current page.

  • to – the index of the last item on the current page.

  • last_page – the last page number.

  • path – The base URL of the search, without any filters or sorting.

  • per_page – the number of items per page.

  • total – the total number of items that match the query.