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.
URL structure
The endpoints can be reached in the following URL structure:
https://{vcf_mr_domain}/verba/restapi/v1/{resource}/{id}?{query_parameters}
The different resources like users, storage targets can be reached dedicated endpoints. To reach a specific entity of the resource the ID must be placed in the URL too.
In some scenarios the request requires to add additional query parameters to modify the response.
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 ore more resources. |
POST | Send sensitive data to trigger a new events such as create new resource, validate password, 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 entity. |
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 are able to specify another tenant during the token generation with the “targetEid” property. In this case the “eid” property should be left out from the request.
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 to generate new access token without user credentials.
Access token generation with 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
Pagination
The listing endpoints uses a server side pagination. The page size can be modified with the “limit” query parameter. In case of the result set 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 a those can be accessed on a 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, that means there are other users that can be listed. So, a next request in 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, no more request is needed.
Query parameters
The listing endpoints allow