REST API

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