API management

Working with the Swagger UI

The Swagger UI describes each service (resource) in the API.

You can select a service and view the endpoints per service and the supported call methods that you can use for each endpoint.

Figure 1. Endpoints for the LabelManager API

When you click the expand icon for an endpoint, you can view the relevant input parameters for a call.

You can try and run API calls on the interactive Swagger UI.

Note: Before you execute a call through the Swagger UI, ensure that you have obtained an API access token, as described in Using the Swagger UI to authenticate. You need this access token when using the Authorize function on the Swagger UI.

From the expanded view of an endpoint, click Try it out. In the request body, the field become editable so you can enter values.

Figure 3. Executing a call on the Swagger UI

Click Execute to send the request. After you click Execute, the Responses section shows the curl command that was submitted and the Request URL. The Server response section shows the code returned by the server.

Retrieving a resource

Use a GET request to retrieve an object or group of objects. When you use the UUID, the request returns a single object in JSON format; if you do not use a UUID, the request returns a JSON list of objects.

Retrieve a list of fabric objects

curl --fail -s -X GET -H "Authorization: Bearer <ACCESS TOKEN>" -H "Content-Type: application/json; charset=utf-8" "https://fss.domain.tld/rest/intentmgr/api/v1/intents"

[
  {
    ...
    "fabric": [
      {
        "deployInfo": {
          "isFailed": false,
          "reason": "Delete Workload workload 1 Deployment Done.",
          "timestamp": "2022-11-22T19:19:12Z",
          "transactionId": "435561924323704832"
        },
        "isDigitalSandbox": false,
        "name": "edge1_realnet_fabric",
        "state": "DeploymentDone",
        "uuid": "434325057192460288",
        "version": "1.0"
      }
    ],
    ...
    "uuid": "434325057192329216",
    "version": "1.0",
    "wlCount": 0
  },
  {
    ...
    "fabric": [
      {
        "deployInfo": {
          "isFailed": false,
          "reason": "Workload APP01 Deployment Done",
          "timestamp": "2022-11-22T22:58:46Z",
          "transactionId": "435584022265987072"
        },
        "isDigitalSandbox": true,
        "name": "DSPOD01_gatenet_fabric",
"state": "DeploymentDone",
        "uuid": "435562509898940416",
        "version": "1.0"
      }
    ],
    ...
    "uuid": "435562509865320448",
    "version": "1.0",
    "wlCount": 0
  }
]

Retrieve a single fabric with its UUID

curl --fail -s -X GET -H "Authorization: Bearer <ACCESS TOKEN>" -H "Content-Type: application/json; charset=utf-8" "https://fss.domain.tld/rest/intentmgr/api/v1/intents/434325057192329216"

{
  ...
  "fabric": [
    {
      "deployInfo": {
        "isFailed": false,
        "reason": "Delete Workload workload 1 Deployment Done.",
        "timestamp": "2022-11-22T19:19:12Z",
        "transactionId": "435561924323704832"
      },
      "isDigitalSandbox": false,
      "name": "edge1_realnet_fabric",
      "state": "DeploymentDone",
      "uuid": "434325057192460288",
      "version": "1.0"
    }
  ],
  ...
  "uuid": "434325057192329216",
  "version": "1.0",
  "wlCount": 0
}

Create a resource

Use a POST request to create a new resource or set of resources. When you create a new object, you must provide a JSON object that contains all the attributes of the object as defined in the API specifications.

Create a label

curl -X 'POST' \
  'https://fss.domain.tld/rest/labelmgr/api/v1/labels' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <ACCESS TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "comments": "",
  "defaultLabel": false,
  "externalID": "",
  "name": "Edge-Link",
  "value": "edgelabel"
}'

{
  "externalID": "",
  "name": "Edge-Link",
  "value": "edgelabel",
  "comments": "",
  "defaultLabel": false
}

Updating an object

Use a PUT request to update an existing object.

Update a label

The following PUT request updates the comments for a label:

curl -X 'PUT' \
  'https://fss.domain.tld/rest/labelmgr/api/v1/labels' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <ACCESS TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "externalID": "",
  "name": "Edge-Link",
  "value": "edgelabel",
  "comments": "Updated Comment",
  "defaultLabel": false
}'

{
  "externalID": "",
  "name": "Edge-Link",
  "value": "edgelabel",
  "comments": "Updated Comment",
  "defaultLabel": false
}

Deleting an object

Use a DELETE request to remove an object or a set of objects.

DELETE requests

The following DELETE request removes minor severity alarms:

curl -X 'DELETE' \
  'https://fss.domain.tld/rest/alarmmgr/api/v1/alarms?severity=minor' \
  -H 'accept: application/json' -H 'Authorization: Bearer <ACCESS TOKEN>'

The following DELETE request removes an alarm with a UUID 424197038574403584:

curl -X 'DELETE' \
  'https://fss.domain.tld/rest/alarmmgr/api/v1/alarms/424197038574403584' \
  -H 'accept: application/json' -H 'Authorization: Bearer <ACCESS TOKEN>'

Bulk API operations

A bulk API request is a single HTTPS request that contains multiple objects instead of a single object. For example, a regular POST requests contains the definition of a single object and creates that object, and then returns the created object. A bulk POST request contains a list of objects (of the same type and with the same hierarchy) where each object is handled individually and created; the return contains a list of created objects instead of a single object.

Bulk API requests use the same URIs as for single object requests. If single object is received, it handles it as regular API call. If a list of objects is received, it handles it as a bulk API request.

Bulk API requests are supported for POST, PUT and DELETE bulk API calls.

Limitations

The maximum number of objects allowed for each bulk operation is as follows:

Table 1. Number of objects per operation
Operation	Number of objects
POST	200
PUT	200
DELETE	150

If request body is a JSON array, it is considered to be a bulk request. The following APIs already support arrays in the body and are not compatible with bulk API requests.

Table 2. Unsupported endpoints
Method	Endpoint	Details
POST/DELETE	/auth/api/{version}/users/:uuid/roles	add or remove role from user
POST/DELETE	/auth/api/{version}/users/:uuid/usergroups	add or remove users from user-group
POST/DELETE	/auth/api/{version}/usergroups/:uuid/users	associate or disassociate user from user-group
POST	/intentmgr/api/{version}/intents/:uuid/fabrics/:fabricid/accept	accept, commit, or update diff

POST and PUT requests

All POST and PUT endpoints that accept the JSON body (object) to create or update an object also expose bulk POST and bulk PUT endpoints.

Create a single region

POST http://fss.domain.tld/rest/intentmgr/api/v1/regions
{ /* single region object*/ }

Create multiple regions

POST http://fss.domain.tld/rest/intentmgr/api/v1/regions
[ { /* region1 object*/ }, { /* region2 object*/ }, { /* region3 object*/ } ]

Delete requests

DELETE endpoints that accept the resource ID in the URI or accept the JSON object as body (as identifier) also expose bulk DELETE endpoints.

Delete devices identified by UUID

The following example deletes a single device by its UUID:

DELETE http://fss.domain.tld/rest/inventory/api/v1/devices/{uuid}

The following example deletes multiple devices identified by their UUIDs:

DELETE http://fss.domain.tld/rest/inventory/api/v1/devices?uuid=1234&uuid=5678&uuid=4534

Delete objects by their labels

The following example deletes a single label identified by its name and value:

DELETE http://fss.domain.tld/rest/labelmgr/api/v1/labels
{ "name": "Tenant", "value": "tenant1" }

The following example deletes multiple labels:

DELETE http://fss.domain.tld/rest/labelmgr/api/v1/labels
[ { "name": "Tenant", "value": "tenant1" }, { "name": "tenant", "value": "tenant2" }, { "name": "tenant", "value": "tenant3" } ]

Bulk API response

A bulk API request can include the following response codes:

Table 3. Response codes
Code	Description
`200`	All actions were successful; information for each object is provided in the body
`207`	Not all actions were successful; check the body for each object to identify the errors
`4XX`	Something is wrong with the entire bulk API request and it cannot be handled; this code is returned when incorrect formatting is used or when too many objects have been provided

Response structure

The response structure allows for the easy handling of the response for each separate object; each object has a unique response. You can use the index in the response to map the response back to each object in the original request. The response also includes the overall status that lists how many actions were successful and how many failed.

The response has the following structure:

{
    "response": [
        {
            "status": $STATUS_CODE_FIRST_OBJECT,
            "data": $RETURN_DATA_FIRST_OBJECT
        },
        {
            "status": $STATUS_CODE_SECOND_OBJECT,
            "data": $RETURN_DATA_SECOND_OBJECT
        }
    ],
    "responseMetadata": {
        "success": $NUMBER_OF_SUCCESSFUL_OBJECTS,
        "failure": $NUMBER_OF_FAILED_OBJECTS,
        "total": $TOTAL_NUMBER_OF_OBJECTS
    }
}

The following table describes the variables in the preceding response message.

Table 4. Variable definitions
Variable	Description
`$STATUS_CODE_*_OBJECT`	This variable specifies the HTTP response code that would be returned if a single object API request had been made with the specified action. For possible values, see Response codes.
`$RETURN_DATA_*_OBJECT`	This variable specifies the HTTP response data that would be returned if a single object API request had been made with the specified action. For instance, it contains the object's data if the creation succeeded or an error output if something went wrong for the object.
`$NUMBER_OF_SUCCESSFUL_OBJECTS`	This variable specifies for how many objects the action was successful.
`$NUMBER_OF_FAILED_OBJECTS`	This variable specifies for how many objects the action failed.
`$TOTAL_NUMBER_OF_OBJECTS`	This variable specifies the total number of objects provided. This value is the sum of `$NUMBER_OF_SUCCESSFUL_OBJECTS` and `$NUMBER_OF_FAILED_OBJECTS`.

Job manager framework

The Fabric Services System API job framework provides a way to handle REST API calls in a non-blocking manner so that the call returns to the invoking client immediately. The job manager manages the life cycle of a job.

At a high level, the job life cycle is as follows:

An API client sends a request.
The job manager creates a new job, validates it, and marks its status as Submitted.
The new job is persisted in the Fabric Services System database.
The job manager sends the client details about the accepted server operation in the form of a job with an ID, tracking URL, and other details.

The client can then use the tracking URL to poll for the job status.

Single auto deploy command request body and response

The following examples show the request body that uses the auto-deploy command and the response from the system.

{
    "command": "AUTO_DEPLOY",
    "params": [
        {
            "key": "intentId",
            "value": 123
        },
        {
            "key": "intentVersion",
            "value": "1.0"
        }
    ]
}

{
    "id": "443896864224313344",
    "requestURI": "",
    "requestMethod": "",
    "command": "AUTO_DEPLOY",
    "params": [
        {
            "key": "intentId",
            "value": 123,
            "type": ""
        },
        {
            "key": "intentVersion",
            "value": "1.0",
            "type": ""
        }
    ],
    "enqueueTime": "2023-01-19T07:19:09.096617184Z",
    "endTime": null,
    "trackingURL": "/jobs/443896864224313344",
    "status": "Submitted",
    "failureReason": "",
    "result": null
}

Bulk API request and response

[
    {
        "command": "AUTO_DEPLOY",
        "params": [
            {
                "key": "intentId",
                "value": 123
            },
            {
                "key": "intentVersion",
                "value": "1.0"
            }
        ]
    },
    {
        "command": "AUTO_DEPLOY",
        "params": [
            {
                "key": "intentId",
                "value": 456
            },
            {
                "key": "intentVersion",
                "value": "2.0"
            }
        ]
    }
]

{
    "response": [
        {
            "data": {
                "id": "443896864224313344",
                "requestURI": "",
                "requestMethod": "",
                "command": "AUTO_DEPLOY",
                "params": [
                    {
                        "key": "intentId",
                        "value": 123,
                        "type": ""
                    },
                    {
                        "key": "intentVersion",
                        "value": "1.0",
                        "type": ""
                    }
                ],
                "enqueueTime": "2023-01-19T07:19:09.096617184Z",
                "endTime": null,
                "trackingURL": "/jobs/443896864224313344",
                "status": "InProgress",
                "failureReason": "",
                "result": null
            },
            "status": 202
        },
        {
            "data": {
                "id": "443896864291422208",
                "requestURI": "",
                "requestMethod": "",
                "command": "AUTO_DEPLOY",
                "params": [
                    {
                        "key": "intentId",
                        "value": 456,
                        "type": ""
                    },
                    {
                        "key": "intentVersion",
                        "value": "2.0",
                        "type": ""
                    }
                ],
                "enqueueTime": "2023-01-19T07:19:09.134867794Z",
                "endTime": null,
                "trackingURL": "/jobs/443896864291422208",
                "status": "Submitted",
                "failureReason": "",
                "result": null
            },
            "status": 202
        }
    ],
    "responseMetadata": {
        "success": 2,
        "failure": 0,
        "total": 2
    }
}

Job retention

The system checks every hour for jobs that are older than 24 hours and purges them from the database to keep storage usage to a minimum.