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:
*
.. raw:: html
See: OpenAPI specification examples.
.. raw:: latex
Refer to the "OpenAPI Specification Examples" section in the HTML API Guide.
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.
*
.. raw:: html
OpenAPI Specification Examples
.. raw:: latex
Refer to the "OpenAPI Specification Examples" section in the HTML API Guide.