API conventions

This section describes the conventions and guidelines for best practices used in the Fabric Services System REST API.

HTTP headers

The Fabric Services System REST API uses HTTP headers for various purposes such as authentication. This section describes the required and supported HTTP headers.

Request Headers

The following headers are required when making HTTP requests:

  • Content-Type: application/json
    The server response is formatted in JSON. Content-Type is a required header field for HTTP POST and PUT requests, and strongly advised for any other HTTP request.
  • Authorization: $AUTHORIZATION_STRING
    Each API call must be authenticated, so the Authorization header must be sent with each request, unless a call is documented as not authenticated. The $AUTHORIZATION_STRING is defined in the API Authentication section.

Response Headers

The system returns the following headers in response to HTTP requests:

  • Content-Type: application/json
    The server response is formatted in JSON.
  • Security Headers: The server also returns multiple security headers including:
    • X-Content-Type-Options: nosniff
    • X-Frame-Options: SAMEORIGIN
    • X-XSS-Protection: 1; mode=block

Server response codes

The Fabric Services System server replies using standard HTTP response codes as described in RFC9110, section 15.

2XX Codes

2XX codes indicate that the request was processed:

Table 1. 2xx code descriptions
Code Description
200 Everything is okay, content is in the body.
201 Everything is okay, the object is created, and the location header points to the object.
204 Everything is okay, but there is no content in the body.

This is the standard reply for an update or a deletion

3XX Codes

3XX codes indicate that further action is needed by the client.

Table 2. 3xx code descriptions
Code Description
300 The request requires a choice to be made for it to succeed. Typically used when a user needs to accept or acknowledge a warning; for instance, when deleting an entity.

4XX Codes

4XX codes indicate that a mistake was made by the client. The body of the response indicates what went wrong with more detail.

Table 3. 4xx code descriptions
Code Description
400 Bad request: something is wrong in the request.
401 Not authenticated (wrong password or wrong API Key).
403 Not authorized (request for something to which you do not have rights).
404 Not found (request something that does not exist).
409 Conflict (the requested change conflicts with existing configuration).
412 Precondition failed (more information is required before this request can succeed).

5XX Codes

Table 4. 5xx code descriptions
Code Description
500 Internal server error. Error is described in the body.
501 Not implemented. The request you made is not supported.

API relationships

Resources have relationships to other objects. Objects in the Fabric Services System API can have the following relationships:
  • 1:n - one-to-many
  • n:m - many-to-many
  • 1:1 - one-to-one

1:n relationships

A parent-to-child relationship is an example of a 1:n relationship. 1:n relationships can expressed in the URI as sub-collections, for example:
  • Collection: /subnets/{id}/sub-interfaces
  • Singleton: /subnets/{id}/sub-interfaces/{id}

n:m relationships

In a n:m relationship, two objects that have a link between each other, but are not in a parent-to-child relationship. A membership in a group exemplifies a many-to-many relationship: a member can belong to many groups; a group has many members, such as the relationship between a User and a User Group.

1:1 relationships

In a 1:1 relationship, a resource is related only to one other resource.

Naming conventions and best practices

URL conventions

The URL path is expressed in lowercase.

https://fss.domain.tld/rest/workloadmgr/api/v2/aclprofiles

instead of:

https://fss.domain.tld/rest/workloadmgr/api/v2/aclProfiles

Attribute naming conventions

  • Attributes are expressed as nouns.

  • Acronyms are all uppercase.

Attributes

Anything that can be managed in the API is an object. Fabric Services System REST API objects have common attributes. Some objects also have an external attribute provided by orchestrators.

ExternalID attribute

The ExternalID attribute specifies the ID used by an orchestrator to track an object in the Fabric Services System API. Orchestrators can use the ExternalID attribute as follows:
  • to correlate external IDs in the systems they orchestrate
  • in audit mechanisms between orchestrators and Fabric Services System, orchestrators can identify the objects that they need to audit/track and which ones to not inspect (that is, those without an externalID)
Table 5. externalID attribute characteristics
Attribute Type Required Description
externalID String of up to 255 characters No The external identifier for the object.
  • You can filter using the externalID value
  • You cannot edit the value.
  • You cannot update with the value with an empty string.
The following objects have the externalID attribute:
  • region
  • deployment queue item
  • fabric intent
  • LAG
  • workload intent
  • workload intent subnet
  • workload intent match label (sub-interface based on label)
  • workload intent sub-interface (sub-interface based on port and interface)
  • label
  • QoS profile
  • ACL profile

API error format

Fabric Services System REST API error handling is implemented according to RFC 7807 Problem Details for HTTP APIs. Errors are reported in the following JSON format:
{
    "type": URI                            
    "title": Translated string             
    "detail": String                      
    "status": Int                          
    "object_ref" optional: URI             
    "errors" optional: [ErrorData]         
    "additional_info" optional: String     
}
Table 6. Field definitions
Name Type Description
type URI Relative name-spaced reference to error definition in docs
title String Fixed String
detail URI Detailed string with IDs and names
status Int HTTP status code
object_ref URI Request URL
errors Array List of errors (if returning with multiple errors in single request)

Single error

{
    "type": "/workloadmgr/api/v1/errors?key=missing-parameter",
    "title": "MISSING_PARAMETER",
    "detail": "[lsIntentFabricType] should be set",
    "status": 400,
    "object_ref": "/workloadmgr/api/v1/intents"
}

The Fabric Services System REST API returns all errors in a request, not just the first one that it encounters. For example, if a POST request fails because an attribute conflicts with another object and also because a mandatory attribute is not provided, both errors are returned. If there are multiple errors, all errors are wrapped in a single predefined error and all real errors are listed in the errors field.

Multiple errors

{
    "type": "/workloadmgr/api/v1/errors?key=multi-error",
    "title": "MULTI_ERROR",
    "detail": "See errors",
    "status": 207,
    "object_ref": "/workloadmgr/api/v1/intents",
    "errors": [
        {
            "type": "/workloadmgr/api/v1/errors?key=missing-parameter",
            "title": "MISSING_PARAMETER",
            "detail": "[lsIntentFabricType] should be set",
            "status": 400,
            "object_ref": "/workloadmgr/api/v1/intents"
        },
        {
            "type": "/workloadmgr/api/v1/errors?key=invalid-parameter",
            "title": "INVALID_PARAMETER",
            "detail": "Invalid parameter value [intentType]",
            "status": 400,
            "object_ref": "/workloadmgr/api/v1/intents"
        },
        {
            "type": "/workloadmgr/api/v1/errors?key=missing-parameter",
            "title": "MISSING_PARAMETER",
            "detail": "[templateName] should be set",
            "status": 400,
            "object_ref": "/workloadmgr/api/v1/intents"
 
        }
    ]
}