Glossary

Resource

An object with type, data, relationships to other resources and set of methods to operate on it. For example, in the endpoint “api/nic/power”, “nic” is a resource which represents NIC-500 device, and “power” is a resource which can respond with serial number and version information from it.

Request

An action performed on a resource. SPIDAR SDK supports GET and PUT type requests. GET requests are used to retrieve data from a resource. PUT request are used to change the resource’s data. Not all resources support both types of requests, please see the resource documentation for more information.

Response

Each request to SPIDAR SDK’s API will generate a standard response. Each response is represented as a JSON dictionary structure with “status”, “message”, “data” and “success” fields. The following example is a response of nic/power resource:

{
  "status": {
    "status_code": 0,
    "message": "The command executed successfully",
    "type": "SUCCESS",
    "source": "nic/power",
    "title": "Success"
  },
  "message": "The command executed successfully",
  "data": {
    "state": 1
  },
  "success": true
}

“status” field is a dictionary structure which describes the execution state of the resource, “message” is a human readable string of status description, “data” is a dictionary structure returned by the resource as the execution result, and “success” is a boolean success indicator of the execution status.

Status

An API status structure will be returned in every response from requests to SPIDAR SDK. This structure contains information that describes the result of a request sent to a resource. This includes whether or not the request was completed successfully and any errors that occurred while executing the request and information to help diagnose the error, etc.

Attributes

Key	Data type	Description
status_code	integer	An integer representing the status returned. A status code of 0 represents success. Each status code will represent a standard status that can be returned. The documentation for each resource explains the expected error codes.
message	string	A human readable description of the status returned. This message will contain additional information about the status.
type	string	One of the following status types will be returned: SUCCESS: Indicates that the command was executed successfully. WARNING: Indicates the request completed but this specific use of the resource is not recommended. ERROR: Indicates that a problem has occurred during the command execution and that it failed to complete successfully. FATAL: Indicates that something has caused a system level issue / crash and that normal operation of the system may not continue without some action taken to restore it. Typically this will mean that something must be rebooted, either a device or the entire system.
source	string	URI of resource that generated this status.
title	string	Short descriptor of the status returned.

Sample SUCCESS status

{
    "status": {
        "status_code": 0,
        "message": "The command executed successfully",
        "type": "SUCCESS",
        "source": "nic/system_information",
        "title": "Success"
    }
}

Sample ERROR status

{
    "status": {
        "status_code": 9,
        "message": "The requested command is not supported",
        "type": "ERROR",
        "source": "nic/unknown_resource",
        "title": "CommandNotSupported"
    }
}

Uniform Resource Identifier (URI)

Name of physical or logical resource accessible through the API.

Uniform Resource Locator (URL)

Address of a URI including the protocol identifier. For example, “http://192.168.20.221:8080/api/nic” is the URL, “nic” is the URI. The SPIDAR SDK API is hosted on port 8080, so it must be included in the URL.