Using the API Reference#

For each resource, a study of the general Reference for Actions in conjunction with the lists of actions for a resource provides the reference for the resource.

The Field Reference for a resource provides payload details. The list below explains the Field Reference for a resource:

  • The field Title is indicated in bold. An asterisk indicates the field is mandatory.

  • If the field Type is an array, its the Field Name has a [n] suffix.

  • Object and array names are listed to provide the context of fields.

  • If a field belongs to an object or an array, the full name is in dot separated notation.

  • Where cardinality is shown, the range is [MinItems..MaxItems].

  • If a field has a Default value, the value is shown.

  • If a field has a Pattern, the regular expression pattern is shown.

In addition, a number of conventions are followed some general guidelines should be noted.

  • The full URL includes the host name: https://[hostname]; for example, https://172.29.232.62

  • Variables are enclosed in square brackets.

  • [hierarchy] is the hierarchy which can be specified as:

    • UUID (Universally Unique Identifier); for example, 1c012432c0deab00da595101 or

    • In dot notation; for example, ProviderName.CustomerName.LocationName

    For a list of available hierarchy UUIDs and their dot notations, refer to the data in the response of the call:

GET /api/data/HierarchyNode/?format=json

  • [pkid] is the ID of the resource instance. Refer to the List action reference for the resource.

  • [filename] refers to a file.

  • where a custom action (with “+” in the URL) is available, the POST method is used to execute the Provisioning workflow with the name following the “+”. For more information, consult the custom workflow section of the API Guide.

Relations, Domain models, and Views may have parameters where the choices are constructed from unexposed models (and that may not be available in the API Reference). You can obtain these choices by using the URL specified in the target attribute of the schema of parameter.

To illustrate, below is an extract of the schema for a model called relation/SystemUser that contains a parameter SSOUser, which links a user in the system to a user in an SSO identity provider server. This is done by mapping the SSO user name (sso_username) of the user in the SSO server (sso_idp) to a user in VOSS Automate (data/User).

The schema of relation/SystemUser shows that the choices that are available from SSO Identity provider servers are stored in the model data/SsoIdentityProvider. The list of SSO identity providers could be obtained by using the URL in the target attribute of the schema.

GET /api/relation/SystemUser/?hierarchy=[hierarchy]
  &format=json
  &schema=1

The following is an extract of the schema of relation/SystemUser:

...

"SSOUser": {
            "items": {
                 "type": "object",
                 "properties": {
                      "sso_username": {
                           "required": true,
                           "type": "string",
                           "description": "The name identifier that is used for
                             an SSO authenticated user.",
                           "title": "SSO Username"
                      },
                      "sso_idp": {
                           "target": "/api/data/SsoIdentityProvider/choices/
                              ?hierarchy=[hierarchy]
                              &field=entity_id
                              &format=json
                              &auth_token=[auth_token]",
                           "format": "uri",
                           "required": true,
                           "choices": [],
                           "target_attr": "entity_id",
                           "target_model_type": "data/SsoIdentityProvider",
                           "title": "SSO Identity Provider",
                           "type": "string",
                           "description": "The entity id of the SSO Identity
                             Provider."
                      },

 ...