VMS API essentials

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

The VMS API product adheres to the following REST principles:

• Authentication: requires authentication to access resources.

• JSON: returns data in a standard JSON format.

• Standard HTTP codes: applies standard HTTP response codes to indicate the request status.

Authentication and access to API

The VMS API offers two main types of requests: public (no authentication required) and private (requiring a bearer token).

• Public API requests don’t require a bearer token for authentication. The Integration API falls under this category of public requests.

• Private API requests require mandatory authentication via a bearer token scheme, a method used for both the VMS Admin API and VMS Client API. Notably, the Integration API is a public request and doesn’t utilize a Bearer token.

For security and access control, the API employs an IP address whitelist. Details are provided in the Manage access to API section below.

Use of the bearer token

Obtain a token: a Bearer token is obtained by sending a POST request to the /token endpoint.

Use a token: For every request to protected API resources, use the obtained Bearer token in a special HTTP Authorization header. The header's value should follow this format:

Authorization: Bearer <token>

Where <token> is the bearer token you received.

Example of using the token in a request header:

Authorization: Bearer eyJ0eXAiSUzI1NiJ9.eyJhdWQi.MHbBUJNRGEl2giGXN3uE

Token verification: the API backend validates the authenticity of the supplied token. Upon successful verification, the server permits the execution of the requested operation.

Handling authentication errors:

401 Unauthorized: you made an authenticated request without an Authorization header or with an invalid bearer token. In that case, simply ensure your bearer token is correct and included, then retry your request.

403 Forbidden: the API server might return a 403 Forbidden status error if the user lacks the necessary permissions to perform the requested operation, even if they have a valid bearer token.

Manage access to API via an IP address whitelist

To ensure the security and restrict access to the API, an IP address whitelist mechanism is employed. Administrators can manage this list using the Artisan command: ip-access:manage. This command provides tools for adding, viewing, and clearing IP addresses or subnets that are permitted for various types of API access.

The syntax for the command is as follows:
php artisan ip-access:manage {type} {ip?} {--fresh} {--show}
Where;

• {type} – is a required argument that defines the type of access for which the whitelist is being managed. Valid values are defined in the App\Models\IpAccess::TYPES constant and include:

  • admin

  • push1st

  • orchestrator

  • ib

  • integration_module

  • billing

  • analytic_video

• {ip?} – an optional argument for the IP address or subnet you want to whitelist. Subnets should be in the IP/mask format (for example, 192.168.1.0/24). If you omit this argument, the command won't add a new IP address.

• --fresh – is an optional flag. If this flag is present, the entire current whitelist for the specified access type will be emptied before a new IP address is added (assuming an IP address is also provided).

• --show – is an optional flag. When used, it displays the current whitelist of IP addresses and subnets configured for the specified access type. 

Examples

• View a whitelist for the billing type:
  php artisan ip-access:manage billing --show

• Add an IP address 192.168.1.100 to the billing type:
  php artisan ip-access:manage billing 192.168.1.100

• Add a subnet 192.168.1.0/24 for the billing type and clear the existing whitelist:
  php artisan ip-access:manage billing 192.168.1.0/24 --fresh

How it works

Using the ip-access:manage command allows administrators to precisely control which IP addresses or IP address ranges are authorized to access protected API routes. A middleware mechanism safeguards the system by checking the incoming request's IP address against a whitelist designated for that specific access type.

Access attempts from IP addresses not on the whitelist will trigger an HTTP 403 Forbidden error, indicating a lack of permission to access the resource.

HTTP headers in an API request play a crucial role in determining how the API processes requests and forms responses.

Request headers

The required header

To ensure proper API interaction and receive responses in the expected format, all API requests must include the HTTP Accept header set to application/json.

Accept: application/json

This header is crucial for the server (backend) to understand if the client supports JSON-formatted responses. It ensures that the server will return all data, including error messages, in JSON format.

Failure to include this header may cause the server to return responses in an unintended format (e.g., HTML), even for errors, because it lacks a clear indication of your preferred data type.

Additional headers

To complete specific tasks within the VMS API, you'll need to include additional headers with your requests. You can find comprehensive details about these required headers on the documentation pages dedicated to each API section.

Set the language for data retrieval

You can control the language of the data you receive from the VMS API to suit your needs.

A dedicated language parameter, hl, allows you to select the language for the retrieved information, such as error messages and other resources. You'll need to apply this parameter to each request individually.

You can use one of the following options:

• In the request, send the hl header with the required localization. Example: Hl:en

• Send the hl field in the request body or as a query parameter. You can pass the hl parameter directly in the URL string of the request. For example, as a GET parameter: https://your.domain/api/v1/items?hl=en.

If you provide the hl field simultaneously in both the request body (or query parameters) and the HTTP request header, the value specified in the header will override.

• If no other options are specified, the localization is set to the default one. You can obtain a list of available languages by querying the available_locales parameter.

Validаtion. Status codes for request processing

VMS employs standard HTTP status codes to indicate whether a request was successful or if an error occurred. This section of the documentation describes the standard HTTP response codes that the VMS API uses to communicate the status of request processing, along with examples of error responses.

HTTP status codes

If a request is successful, the server sends the client the OK status, identified by a 2xx code.

When an operation encounters an error, the server responds with a message describing the issue and an appropriate 4xx or 5xx status code.

Validation of the request with an error

When an operation fails, the server sends the client an error message along with an HTTP status code. These codes indicate whether the issue is client-related (400-499) or server-related (500-599).

The API generally provides error messages in a predefined format; however, alternative structures may be employed based on the nature of the request.

{
    "message": "No error message here",
    "errors": {
        "any_key": [
            "Error details"
        ]
    }
}

• the message object – while the message object usually remains empty and doesn't hold error information, there are exceptions. For instance, with an error code of 400, it might include an error description.

• the errors object – details issues encountered during a request. Its keys highlight problematic request fields, though errors can also arise independently of specific fields. The errorsobject can contain multiple errors.

Example

The request includes the url field set to http//example.com. This field has a validation rule requiring it to be a valid URL and no longer than 10 characters. There's also the date field with the value 2000-01-01, which needs to follow the Y-m-d H:i:s format.

The response for this request will be as follows:

{
    "message": "Submitted data was invalid",
    "errors": {
        "url": [
            "The URL value is in invalid format",
            "The URL can be no longer than 10 characters"
        ],
        "date": [
            "The date field doesn't match the format: Y-m-d H:i:s."
        ]
    }
}

 Pagination

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://your.domain/url?page=1",
        "last": "https://your.domain/url?page=4",
        "prev": null,
        "next": "https://your.domain/url?page=2"
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "to": 25,
        "last_page": 4,
        "path": "https://your.domain/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. The links within this object are generated based on the query parameters (filters and sorting):

  • first – the URL to retrieve the first page of results.

  • last – the URL to retrieve the last page of results.

  • prev – the URL to retrieve the previous page of results.

  • next – the URL to retrieve the next page of results.

• meta– metadata describing the organization of the data, including pagination parameters like the current page, number of items, total number of pages, page size, and navigation information for the pages.

  • current_page – the current page number.

  • from –the starting item number for the current page.

  • to – the ending item number for the current page.

  • last_page – the last page number.

  • path – the URL of the request without parameters.

  • per_page – the number of items per page.

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