API conventions

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 is 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, as listed in the following table:

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, as listed in the following table:

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, as listed in the following table. 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 for 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

5xx codes indicate a problem caused by the server

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 an 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 or track and which ones to not inspect (that is, those without an externalID)

The following table describes the externalID attribute:

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     
}

The following table defines the fields in the error message:

Table 6. Field definitions
Name	Type	Description
`type`	URI	Uniform resource identifier for the relative name-spaced reference to the error
`title`	String	Fixed string
`detail`	URI	Detailed string with IDs and names
`status`	Integer	HTTP status code
`object_ref`	URI	Request URL
`errors`	Array	List of errors (if returning with multiple errors in single request)

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.

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"
}

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"
 
        }
    ]
}