Using the REST API

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.

1 URL structure
2 HTTP Method
3 Authentication
4 Query parameters
- 4.1 Pagination
- 4.2 Filtering
- 4.3 Sorting

URL structure

The endpoints can be reached in the following URL structure:

https://{vcf_mr_domain}/verba/restapi/v1/{resource_plural}/{id}?{query_parameters}

The different resources like users and storage targets can be reached by dedicated endpoints. These endpoints allow to list entities of a resource. To reach a specific entity the ID must be placed in the URL too.

In some scenarios, the request requires to add additional query parameters to modify the response.

The resource endpoints usually have options endpoints too. These endpoints list dynamic values that are relevant to the usage of the specific resource endpoint. The URL structure of the option endpoints is the following:

https://{vcf_mr_domain}/verba/restapi/v1/{resource_singular}Options/{option_method}

URL parameter	Description	Example

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

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.

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

POST https://{vcf_mr_domain}/verba/restapi/v1/auth/token

{
  "client_id": "user_login",
  "client_secret": "secret_plain_password",
  "eid": "user_own_tenant"
}

Response

{
  "access_token": "fL9QPL2U667bBpitMFhtNIn2kLHC15WB",
  "refresh_token": "mE07g3HZkoSaqkysDZLC6B3JA0stEiUz0maA9fu1GhblAQc3",
  "token_type": "Bearer",
  "expires_in": 3600,
  "user_id": 12
}

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

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.

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.

If the original request contained query parameters, then these parameters are encoded into the next page token. Therefore only the next page token should be sent to the request, the other query parameters should be removed.

Request for 1st page

With the following request, the page size is maximized in 2 entities. If there is any more entity in the system that could be listed then those can be accessed on the next page.

GET https://{vcf_mr_domain}/verba/restapi/v1/users?limit=2

Response with the 1st page

{
    "nextPageToken": "4ifAzqxn7aI3UdCMzngVWE92NFQ",
    "list": [
        {
            "id": 1348,
            "name": "Test user 1",
            "login": "test_user_1",
            "email": "test_user_1@verba.com"
        },
        {
            "id": 1590,
            "name": "Test user 2",
            "login": "test_user_2",
            "email": "test_user_2@verba.com"
        }
    ]
}

In the response, the next page token is represented, which means there are other users that can be listed. So, a next request is necessary.

Request for 2nd page

GET https://{vcf_mr_domain}/verba/restapi/v1/users?nextPageToken=4ifAzqxn7aI3UdCMzngVWE92NFQ

Response with the 2nd page

{
    "list": [
        {
            "id": 1595,
            "name": "Test user 3",
            "login": "test_user_3",
            "email": "test_user_3@verba.com"
        }
    ]
}

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.

{
	"filtersList": [
		{
			"field": "login",
			"operator": "STARTS_WITH",
			"values": ["john"]
		},
		{
			"field": "id",
			"operator": "GREATER_THAN_OR_EQUAL",
			"values": [100]
		}
	]
}

The example above can be used to search for user entities whose “login” property starts with “john” and whose “id” property is greater or equal to 100.

Not necessarily every property of an entity can be used for filtering. Also, the available operators may be different for the different types of properties.

The supported properties for filtering can be retrieved from a specific endpoint. Every resource type has its own “options” endpoints. The naming convention of that endpoints follows the structure: /v1/{resource_singular}Options/getAllowedFilters

The following example lists the allowed filtering properties and their allowed operators for user entities.

Request

GET https://{vcf_mr_domain}/verba/restapi/v1/userOptions/getAllowedFilters

Response

[
    {
        "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.

Not necessarily every property of an entity can be used for sorting.

The supported properties for sorting can be retrieved from a specific endpoint. Every resource type has its own “options” endpoints. The naming convention of that endpoints follows the structure: /v1/{resource_singular}Options/getSortableFields

The following example lists the allowed sorting properties for user entities.

Request

GET https://{vcf_mr_domain}/verba/restapi/v1/userOptions/getSortableFields

Response

[
    "login",
    "id"
]