Cisco Baseboard Management Controller REST API Guide for Cisco UCS C885A M8 Rack Server, Release 1.0

Introduction

Representational state transfer (REST) or RESTful web services allow you to provide interoperability between computer systems on the Internet. Using the REST-compliant web services you can request systems to access and manipulate textual representations of web resources using a uniform and predefined set of stateless operations. Cisco has now built capabilities of using RESTful APIs to configure the UCS C-series servers using the Redfish™ technology.

Redfish™ is an open industry standard specification and schema that specifies a RESTful interface and utilizes JSON and OData to help customers integrate solutions within their existing tool chains. It utilizes a range of scalable IT technologies that are widely used, and by using these accepted technologies, it makes the use of Redfish™ easier. Redfish™ is sponsored and controlled by the Distributed Management Task Force, Inc. (DMTF), a peer-review standards body recognized throughout the industry.

For more information on DMTF and Redfish™ standards, see DMTF and Redfish™.

Redfish Schema and Specification

Table 1. Redfish Schema and Specification
Release	Redfish Schema	Redfish Specification
Release 1.0.0.240001	2022.2	v1.9.0

HTTP Methods

The following HTTP methods are used to implement different actions, as described below.


HTTP Method	Description
POST	The first method is used to create a new resource. The POST request is submitted to the resource collection in which the new resource is to belong. Submitting a POST request to a resource representing a collection is equivalent to submitting the same request to the Members property of that resource. The last method is used to initiate operations on the object (such as Actions). Services shall support the POST method for sending actions. The POST operation may not be idempotent.
GET	The GET method is used to retrieve a representation of a resource. That representation can either be a single resource or a collection.
PUT	The PUT method is used to completely replace a resource. Properties omitted from the request body are reset to their default value.
PATCH	The PATCH method is the preferred method used to perform updates on pre-existing resources. Changes to the resource are sent in the request body. Properties not specified in the request body are not directly changed by the PATCH request. The response is either empty or a representation of the resource after the update was done. The implementation may reject the update operation on certain fields based on its own policies and, if so, shall not apply any of the update requested.
DELETE	The DELETE method is used to remove a resource. Services shall support the DELETE method for resources that can be deleted.

Status Code

HTTP defines status codes that can be returned in response messages.


Status Code	Status Name	Description
200	OK	The request was successfully completed and includes a representation in its body.
201	Created	A request that created a new resource completed successfully. The Location header shall be set to the canonical URI for the newly created resource. A representation of the newly created resource may be included in the response body.
202	Accepted	The request has been accepted for processing, but the processing has not been completed. The Location header shall be set to the URI of a Task resource that can later be queried to determine the status of the operation. A representation of the Task resource may be included in the response body.
204	No Content	The request succeeded, but no content is being returned in the body of the response.
301	Moved Permanently	The requested resource resides under a different URI.
302	Found	The requested resource resides temporarily under a different URI.
304	Not Modified	The service has performed a conditional GET request where access is allowed, but the resource content has not changed. Conditional requests are initiated using the headers If-Modified-Since and/or If-None-Match to save network bandwidth if there is no change.
401	Unauthorized	The authentication credentials included with this request are missing or invalid.
403	Forbidden	The server recognized the credentials in the request, but those credentials do not possess authorization to perform this request.
404	Not Found	The request specified a URI of a resource that does not exist.
405	Method Not Allowed	The HTTP verb specified in the request (e.g., DELETE, GET, HEAD, POST, PUT, PATCH) is not supported for this request URI. The response shall include an Allow header which provides a list of methods that are supported by the resource identified by the Request-URI.
406	Not Acceptable	The Accept header was specified in the request and the resource identified by this request is not capable of generating a representation corresponding to one of the media types in the Accept header.
409	Conflict	A creation or update request could not be completed because it would cause a conflict in the current state of the resources supported by the platform (for example, an attempt to set multiple attributes that work in a linked manner using incompatible values).
410	Gone	The requested resource is no longer available at the server and no forwarding address is known. This condition is expected to be considered permanent. Clients with link editing capabilities SHOULD delete references to the Request-URI after user approval. If the server does not know, or has no facility to determine, whether or not the condition is permanent, the status code 404 (Not Found) SHOULD be used instead. This response is cacheable unless indicated otherwise.
411	Length Required	The request did not specify the length of its content using the Content-Length header (perhaps Transfer-Encoding: chunked was used instead). The addressed resource requires the Content-Length header.
412	Precondition Failed	Precondition (such as OData-Version, If Match or If Not Modified headers) check failed.
415	Unsupported Media Type	The request specifies a Content-Type for the body that is not supported.
500	Internal Server Error	The server encountered an unexpected condition that prevented it from fulfilling the request.
501	Not Implemented	The server does not (currently) support the functionality required to fulfill the request. This is the appropriate response when the server does not recognize the request method and is not capable of supporting the method for any resource.
503	Service Unavailable	The server is currently unable to handle the request due to temporary overloading or maintenance of the server.

Authentication

The BMC is required to use authentication to access specific Redfish resources. Redfish offers a method of access known as HTTPS Basic Authentication, as defined by RFC7617, enabling users to access Redfish resources. This method uses only connections that conform to TLS to transport the data between any third-party authentication service and clients. Use local BMC authentication or remote authentication like LDAP or Active Directory to log in.

Example of applying for HTTPS basic Authentication using curl:

#

#UCS-Server: /logs$ curl -k -X GET https://<username>:<password>@<BMC IP>/redfish/v1 | jq. 
%Total %Received %xferd Average Speed   Time    Time    Time     Current
                        Dload   Upload  Total   Spend    Left    Speed
100 1532 100 1532 0 0   10281       0--:--:--:--:--: :--: :--:   10281{
    "@odata.id": "/redfish/v1",
    "@odata.type": "#ServiceRoot.v1_11_0.ServiceRoot",
    "AccountService": {
        "@odata.id": "/redfish/v1/AccountService"
    },
    "Cables": {
        "@odata.id": "/redfish/v1/Cables"
    },
    "CertificateService": {
        "@odata.id": "/redfish/v1/CertificateService"
    },
    "Chassis": {
        "@odata.id": "/redfish/v1/Chassis"
    },
    "EventService": {
        "@odata.id": "/redfish/v1/EventService"
    },
    "Id": "RootService",
    "JsonSchemas": {
        "@odata.id": "/redfish/v1/JsonSchemas"
    },
    "Links": {
        "Sessions": {
            "@odata.id": "/redfish/v1/SessionService/Sessions"
        }
    },
    "Managers": {
        "@odata.id": "/redfish/v1/Managers"
    },
    "Name": "Root Service",
    "ProtocolFeaturesSupported": {
        "DeepOperations": {
            "DeepPATCH": false,
            "DeepPOST": false
        },
        "ExcerptQuery": false,
        "ExpandQuery": {
            "ExpandAll": false,
            "Levels": false,
            "Links": false,
            "NoLinks": false
        },
        "FilterQuery": false,
        "OnlyMemberQuery": true,
        "SelectQuery": true
    },
    "RedfishVersion": "1.9.0",
    "Registries": {
        "@odata.id": "/redfish/v1/Registries"
    },
    "SessionService": {
        "@odata.id": "/redfish/v1/SessionService"
    },
    "Systems": {
        "@odata.id": "/redfish/v1/Systems"
    },
    "Tasks": {
        "@odata.id": "/redfish/v1/TaskService"
    },
    "TelemetryService": {
        "@odata.id": "/redfish/v1/TelemetryService"
    },
    "UUID": "1b187d13-66a7-4429-8496-b497d28931ba",
    "UpdateService": {
        "@odata.id": "/redfish/v1/UpdateService"
    }
}

Available APIs

The following Redfish defined URIs are supported:


Resource	Resource URI
Service Root	/redfish/v1/
Account Service	/redfish/v1/AccountService
Manager Account Collection	/redfish/v1/AccountService/Accounts
Manager Account	/redfish/v1/AccountService/Accounts/{{account_instance}}
Role Collection	/redfish/v1/AccountService/Roles
Role	/redfish/v1/AccountService/Roles/{{role_instance}}
Certificate Management	/redfish/v1/CertificateService
Chassis Collection	/redfish/v1/Chassis
Chassis	/redfish/v1/Chassis/{{chassis_instance}}
Manager Collection	/redfish/v1/Managers
Manager	/redfish/v1/Managers/{{manager_instance}}
Managers Network Protocol	/redfish/v1/Managers/{{manager_instance}}/NetworkProtocol
Log Service Collection (Manager)	/redfish/v1/Managers/{{manager_instance}}/LogServices
Log Service Collection (Systems)	/redfish/v1/Systems/{{System_Instance}}/LogServices
Log Service	/redfish/v1/Managers/{{manager_instance}}/LogServices/ {{manager_log_instance}}
Task Service	/redfish/v1/TaskService
Task Collection	/redfish/v1/TaskService/Tasks
Task	/redfish/v1/TaskService/Tasks/{{Task_Instance}}
Log Entry Collection	/redfish/v1/Managers/{{manager_instance}}/LogServices/ {{manager_log_instance}}/Entries
Log Entry Collection (Systems)	/redfish/v1/Systems/{{System_Instance}}/LogServices/ {{LogService_Instance}}/Entries redfish/v1/Managers/{{Manager_Instance}}/LogServices/ {{LogService_Instance}}/Entries
Log Entry (Systems)	/redfish/v1/Managers/{{Manager_Instance}}/LogServices/{{LogService_Instance}} /Entries/{{Entry_Instance}} /redfish/v1/Systems/{{System_Instance}}/LogServices/{{LogService_Instance}} /Entries/{{Entry_Instance}}
Log Entry (Manager)	/redfish/v1/Managers/{{manager_instance}}/LogServices/{{manager_log_instance}} /Entries/{{manager_logentry_instance}}
Ethernet Interface Collection	/redfish/v1/Managers/{{manager_instance}}/EthernetInterfaces
Ethernet Interface	/redfish/v1/Managers/{{manager_instance}}/EthernetInterfaces/{{manager_ethifc_instance}}
Event Service	/redfish/v1/EventService
Session Service	/redfish/v1/SessionService
Session Collection	/redfish/v1/SessionService/Sessions
Session	/redfish/v1/SessionService/Sessions/{{session_id}}
Update Service	/redfish/v1/UpdateService
FirmwareInventory Collection	/redfish/v1/UpdateService/FirmwareInventory
FirmwareInventory	/redfish/v1/UpdateService/FirmwareInventory/{{firmwareinventory_instance}}
Registries	/redfish/v1/Registries
System	/redfish/v1/Systems

ODATA Properties

OData Properties are used to provide information on the resource like its ID, type, context, and so on accessed by an URI. The following are the properties used in REST API:

Table 2. OData Attributes
Name	Type	Read only	Description
@odata.id	String	True	This property is your unique identifier for the resource. It follows the format defined in the Redfish specification.
@odata.type	String	True	This property is an absolute URL that specifies the resource type. It follows the format defined in the Redfish specification. The type values for each Redfish entity indicate the schema it follows, as listed in the Redfish API under the Schema column.

Example

{
"@odata.id": "/redfish/v1/",
"@odata.type": "#ServiceRoot.v1_11_0.SesrviceRoot"
}

Resource

The resource properties specified in this topic are inherited by all APIs mentioned in this document. The following are the different Resource schema properties:

Table 3. Resource Type Definitions
Name	Type	Read only	Description
ID	String	True	This property uniquely identifies the resource among similar resources.
Description	Null, String	True	This property gives a description of the resource and ensures consistency in schema definitions.
Name	String	True	This property indicates the name of the resource.
UUID	String	True	This property follows the pattern: ([0-9a- f]{8}-[0-9a-f]{4}-[0-9a- f]{4}-[0-9a-f]{4}-[0-9a- f]{12}).

Table 4. Location Definitions
Name	Type	Read only	Description
PartLocation	Object	True	This property indicates where the part is located within an enclosure.
ServiceLabel	String	True	This property is the label of the part location, such as a silk-screened name or a printed label.
LocationOrdinalValue	Number	True	This property represents the numerical position of the part. For example, if the LocationType is Slot and the unit is in slot 2, then this value is 2.
LocationType	String	True	This property specifies the type of location of the part. Backplane: A backplane. Bay: A bay. Connector: A connector or port. Embedded: Embedded within a part. Slot: A slot. Socket: A socket.

Table 5. Status Definitions
Name	Type	Read only	Description
Health	String	True	This property shows the health status of the resource without its dependent resources. Enum Options: OK: Normal. Warning: A condition needs your attention. Critical: A critical condition needs immediate attention.
HealthRollup	String	True	This property indicates the overall health status from the perspective of this resource. Enum Options: OK: Normal. Warning: A condition needs your attention. Critical: A critical condition needs immediate attention.
State	String	True	This property specifies whether the resource is enabled or disabled. Enum Options: Enabled: This function or resource is enabled. Disabled: This function or resource is disabled.

Service Root

This resource represents the root of the Redfish service, located at the "/redfish/v1/" URI. As a hypermedia API, all other resources accessible through the Redfish interface on this device are linked directly or indirectly from the Service Root.

GET

https://<username>:<password>@<BMC IP>/redfish/v1
Content-Type:application/json

Response

The response of the request will be in JSON format. The properties are mentioned in the following table.

Table 6. Service Root Properties
Name	Type	Read only	Description
AccountService	Object	True	Provides a link to the Account Service.
Cables	Object	True	Not supported.
CertificateService	Object	True	Provides a link to the Certificate Service.
Chassis	Object	True	Provides a link to the collection of Chassis.
EventService	Object	True	Provides a link to the Event Service.
Id	String	True	See Resource for more details.
JsonSchemas	Object	True	Links to a collection of JSON schema files.
Links	Object	True	Contains links to related resources: Sessions: Provides a link to the collection of Sessions. ManagerProvidingService: Provides a link to the collection of Managers.
Managers	Object	True	Provides a link to the collection of Managers.
Name	String	True	See Resource for more details.
Oem	Object	True	Contains OEM extensions.
ProtocolFeaturesSupported	Object	True	Details supported protocol features: DeepOperations: See Table 2 for properties. ExcerptQuery: Indicates if the 'excerpt' query parameter is supported. ExpandQuery: Contains details about using $expand in the service. See Table 3 for properties. FilterQuery: Indicates if the $filter query parameter is supported. OnlyMemberQuery: Indicates if the 'only' query parameter is supported. SelectQuery: Indicates if the $select query parameter is supported.
RedfishVersion	String	True	This string represents the version of the Redfish service.
Registries	Object	True	Links to a collection of Registries.
SessionService	Object	True	Provides a link to the Session Service.
Systems	Object	True	Provides a link to the collection of Systems.
Tasks	Object	True	Provides a link to the Task Service.
TelemetryService	Object	True	Provides a link to the Telemetry Service.
UUID	String	True	See Resource for more details.
UpdateService	Object	True	Provides a link to the Update Service.

Table 7. DeepOperations Properties
Name	Type	Read only	Description
DeepPATCH	Boolean	True	An indication of whether the service supports the deep PATCH operation.
DeepPOST	Boolean	True	An indication of whether the service supports the deep POST operation.

Table 8. ExpandQuery Properties
Name	Type	Read only	Description
Expand All	Boolean	True	Indicates if the service supports expanding all entries using the $expand asterisk (*).
Levels	Boolean	True	Indicates if the service supports the $levels qualifier for expansion.
Links	Boolean	True	Indicates if the service supports expanding only entries in the Links section using the $expand tilde (~).
NoLinks	Boolean	True	Indicates if the service supports expanding only entries not in the Links section using the $expand period (.).

Collection

Table 9. Collection Properties
Name	Type	Read only	Description
@odata.id	String	True	See ODATA Properties for more details.
@odata.type	String	True	See ODATA Properties for more details.
Members	Array	True	Holds the members of this collection.
Members@odata.count	Number	True	Indicates the number of members in the collection.
Name	String	True	Specifies the name of the collection.
Description	String	True	Provides details about the resource.

Bias-Free Language

Book Title

Cisco Baseboard Management Controller REST API Guide for Cisco UCS C885A M8 Rack Server, Release 1.0

Chapter Title

Cisco BMC REST API Overview

Results

Chapter: Cisco BMC REST API Overview