REST API Basics

The REST API provides create, update, get, and delete operations on platform management resources. The resources are grouped in the following categories:

• Agents and Gateways
• Alerts
• Automation
• Exports
• Integrations
• Knowledge Base
• Metrics
• Monitoring
• Patching
• Resource Management
• Tenancy and Access Controls
• Tickets

View a summary of resource endpoints and operations in the next section.

The following topics describe basic REST API capabilities.

Authentication

The API supports OAuth 2.0 authentication. All API requests require authentication.

To authenticate API requests you need to provide an ID and authentication token with the request. When you set up a custom integration, providing your credentials and specifying ‘OAUTH2’ authentication, you receive:

• tenant ID
• key
• secret

Use the key and secret values in the /auth/oauth/token API request to get the authentication token for subsequent API requests. The response provides the authentication token in the access_token field and the time interval for which the token is valid, in seconds, in the expires-in field.

Use the authentication token and tenant ID to authenticate subsequent API requests, passing the authentication token in the request header:

"Authorization: Bearer {authenticationToken}"

Where required, pass the tenant ID as a path parameter.

Base URL

The API fully supports domain-specific partner and client URLs.

Partners

Custom brand partners use a base URL that has the following format:

https://{partnerName}.api.vistanet.jp/api

The {partnerName} part of the URL is a path parameter, which is replaced by the partner domain name. For example, the base URL for partner Alpha is: https://alpha.api.vistanet.jp/api.

All other partners use the following base URL:

https://api.vistanet.jp/api

Clients

The base URL for a client who uses custom branding while the partner does not use custom branding is: https://api.vistanet.jp/api.

Clients and partners who both use custom branding use the client URL, which has the following format:

https://{clientName}.api.vistanet.jp/api

For example, if both partner Alpha and client Acme are private-labeled, the base URL is https://acme.api.vistanet.jp/api.

URL path parameters

The API documentation indicates variable URL path parameters using brackets: {pathParameter}. This permits operations on specific resources. For example, a tenant ID path parameter is represented as {tenantID}. When making an API request that requires a tenant ID to be specified, replace {tenantID} with the actual tenant ID.

Versioning

API versioning ensures application and service compatibility. All API requests include an API version specification.

The API version identifier is appended to the base URL. For example, API version v2 has the following URL format:

https://api.vistanet.jp/api/v2

HTTP request header

Use the following request header fields to provide data format and authentication information:

HTTP response header

the HTTP response header includes rate limit information for adjusting the API request frequency to accommodate performance and service changes.

HTTP methods

The API supports the following methods:

Data encoding

The API supports JSON data encoding of request and response data.

Specify JSON encoding in the HTTP header Content-Type and Accept fields.

HTTP status codes

These status codes are returned by the APIs:

Rate limit

The rate limit specifies the number of requests an API server accepts within a time interval to ensure quality of service. If the number of API requests exceeds the rate limit, requests are throttled. The request rate is expressed in requests-per-minute.

Using the rate limit information returned in the response headers permits applications to self-regulate API requests.

The following rate limits apply to each service provider, partner, and client, according to resource category.

A request that is rejected because it exceeds the rate limit returns a HTTP 429 Too Many Requests status code with the following error information in the response body:

{
    "error" : "throttled",
    "error_description" : "Too Many Requests"
}

Additional rate limit errors received within one minute of the first error are not processed.