The endpoints in the v1 REST API allow the client to query, list, and modify different resources in the system. This article contains the basic usage of the v1 REST API endpoint.
| Table of Contents |
|---|
URL structure
The endpoints can be reached in the following URL structure:
...
URL parameter | Description | Example |
|---|---|---|
vcf_mr_domain | Domain or the IP address of the VFC MR or Combo server installation, where the VFC Web Application can be reached | “localhost” |
resource_plural | Name of the resource type in plural form | For the user resource: “users” |
resource_singular | Name of the resource type in singular form | For the user resource: “user” |
id | The uni |
HTTP Method
On the same resource, different actions can be achieved with different HTTP methods if applicable. The actions are collected in the following table.
Method | Action description |
|---|---|
GET | Retrieve one or more resources. |
POST | Send sensitive data to trigger new events such as creating a new resource, validating passwords, etc. |
PUT | Update a specific entity. As a payload a full object is necessary. |
PATCH | Update a specific entity. As a payload, a partial object is enough. |
DELETE | Delete specific entities. |
Authentication
To use the REST API endpoints the client has to authenticate themselves. With the Authentication endpoint access token and refresh token can be generated. The protected endpoints can be used with the access token.
| Panel | ||||||
|---|---|---|---|---|---|---|
| ||||||
In the case of a multitenant system, the generated access token is only valid for a certain tenant. By default, the token is valid only for the authenticated user’s tenant. But if the client user is in the reference tenant, then they can specify another tenant during the token generation with the “targetEid” property. In this case, the “eid” property must be “0000”. |
Access token generation with credential
Request
| Code Block |
|---|
POST https://{vcf_mr_domain}/verba/restapi/v1/auth/token
{
"client_id": "user_login",
"client_secret": "secret_plain_password",
"eid": "user_own_tenant"
} |
...
The access token has an expiration, that is specified in the response too. That access token can be used to use the other endpoints. The refresh token has no expiration, it can be stored. The refresh token allows the generation of a new access token without user credentials.
Access token generation with a refresh token
| Code Block |
|---|
POST https://{vcf_mr_domain}/verba/restapi/v1/auth/token
{
"client_id": "user_login",
"refresh_token": "mE07g3HZkoSaqkysDZLC6B3JA0stEiUz0maA9fu1GhblAQc3"
} |
Access token usage
The generated access token is a bearer token. The token must be placed in the Authorization header.
| Code Block |
|---|
GET https://{vcf_mr_domain}/verba/restapi/v1/users
Authorization: Bearer fL9QPL2U667bBpitMFhtNIn2kLHC15WB |
Query parameters
The listing endpoints allow influencing the response list with different query parameters. The following section covers the different actions that are available with the query parameters.
Pagination
The listing endpoints use server-side pagination. The page size can be modified with the “limit” query parameter. In case of the resultset would contain more entities than the page side a “nextPageToken” property is represented in the response. That token can be used to navigate to the next page. If there isn’t a “nextPageToken” property in the response, then there are no more entities.
...
In the response, there is no next page token, so there is no more page to display, and no more request is needed.
Filtering
With the “filters” query parameter filtering criteria list can be set to reduce the result list for certain entities. The filters are in a JSON structure which is shown below. If there are multiple filtering criteria, the system links them with the logical AND operator.
...
| Code Block |
|---|
[
{
"operators": [
"EQUAL",
"NOT_EQUAL",
"GREATER_THAN",
"GREATER_THAN_OR_EQUAL",
"LESS_THAN",
"LESS_THAN_OR_EQUAL",
"CONTAINS",
"ENDS_WITH",
"STARTS_WITH",
"LIKE",
"BETWEEN",
"IN",
"NOT_IN"
],
"paramName": "login"
},
{
"operators": [
"EQUAL",
"NOT_EQUAL",
"GREATER_THAN",
"GREATER_THAN_OR_EQUAL",
"LESS_THAN",
"LESS_THAN_OR_EQUAL",
"BETWEEN",
"IN",
"NOT_IN"
],
"paramName": "id"
}
] |
Sorting
The order of entities in the list response can be modified with the “sortBy“ and the “sortOrder“ query parameters. The allowed values of the “sortOrder” parameter are “asc” for ascending and “desc” for descending order.
...