Introduction to Automate OpenAPI Examples

Overview

This section of the API Guide describes a number of use-cases for integrating with VOSS Automate, based on the OpenAPI specification.

Note

The OpenAPI specification (formerly called Swagger) defines a standard, language-agnostic interface to RESTful APIs. OpenAPI definition files are written in the YAML format, which is automatically rendered into a more human-readable interface.

See https://swagger.io/specification/

You can use the REST API to interact programmatically with Automate and integrate with external applications, such as ServiceNow. For example, you can use the example calls to retrieve a list of all customers at the Provider hierarchy, retrieve a list of all sites belonging to a customer, add a phone or a subscriber, update phone or line details, or delete a phone or a subscriber.

Note

The OpenAPI examples do not support interactive API calls to VOSS Automate.

Errors

The API uses standard HTTP status codes to indicate the success or failure of the API call.

The Automate API uses conventional HTTP response codes to indicate the success or failure of an API request. Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided, for example, a required parameter was omitted.

Samples

Each API call has one or more documented examples, for either a response or request (depending on the method, either GET, POST, PATCH, or DELETE).

The body of the response is JSON format.

The response samples provided for the GET call depend on the macro you provide for the call, a sample response is provided for each input macro parameter. Click the drop-down at Example to view the response sample for the relevant input macro.

Request samples are similarly provided for each POST, PATCH, and DEL call. Where more than one example is provided, click the drop-down at Example to toggle the examples for the call.

You can view the samples, here:

• See: OpenAPI specification examples.

Content Type

The VOSS Automate API supports the application/json content type by default.

VOSS Automate API and the OpenAPI Specification Examples

These links provide further details relevant to the OpenAPI examples:

• Automate API Guide (this document)

  The Automate API Guide provides general information for the Automate API, which you can use as references for the examples in this section:

  • What are models?

  • What are model types?

  • What is the importance of “hierarchy” in the API?

  • Request and response patterns

  • API URL structure

  • Headers

  • Authentication

  • Authorization

  • HTTP methods

  • API parameters

  • Request headers

  • Login and authorization tokens

  • API responses

  • Optional request metadata

  • Using the API Reference

  • API schema

• API Model Reference

  The API Model Reference provides resource details. Resources are classified by the type of model in the system (data, device, domain, relation or view), for example, data/AccessProfile or device/cucm/Phone.

  Depending on the installed modules and their feature packages, the API of feature package models may be available, for example, relation/Subscriber or view/QuickSubscriber.

  The documentation for each API example contains a link to the model reference for that call.

• API Reference

  The API Reference describes the schema and the operations applicable for each resource in the system. The documentation for each API example contains a link to the API reference for that call.

• OpenAPI Specification Examples