How to determine the JSON response format?

siaoleio
Minnow

Posts: 11

How to determine the JSON response format? Jan 28, 2021 7:18:24 GMT

Quote

Post by siaoleio on Jan 28, 2021 7:18:24 GMT

Hello everyone,
I am developing a redfish service. However, I do not know what kind of JSON payload should I return to client when they are requesting an action. For example, if the client sends a post request to the /redfish/v1/Systems/1/Actions/ComputerSystem.Reset, and the operation is success, what json payload should I return?

I see the redfish specification shows that:

10.5.13.2 Action responses

Response payloads for actions may contain a JSON body that is described by the schema definition for the action.

See the Schema definition languages clause for the representation of these definitions. Actions that do not define a

response body may provide an error response in the response payload.

But I have following questions:
1) It seems that the xml or json schema file does not provide any responese related infomation.
2) Do this means I can return any kind of response? And the specification recommand to return the "error response" format?
so, if the client reset operation is success, I can return 204 no content, or 200 with an error respones like:

{
"error": {
"code": "Base.1.8.Success",
"message": "Successfully Completed Request",
"@message.ExtendedInfo": [
{"@odata.type": "#Message.v1_1_1.Message",
"MessageId": "Base.1.8.Success",
"Message": "Successfully Completed Request",
"Severity": "OK",
"MessageSeverity": "OK",
"Resolution": "None"
}]
}
}
, is this correct?

With kindest regards.

mraineri
Administrator

Posts: 1,132

How to determine the JSON response format? Jan 28, 2021 15:30:04 GMT siaoleio likes this

Quote

Post by mraineri on Jan 28, 2021 15:30:04 GMT

Most actions don't define a response body. In those cases, you can either use 204 with no body, or use a 200 with the "error" object as you've highlighted. If you're using 200, you cannot use other types of formats beyond the error object. The error object is a bit strange in this case, but this is behavior we've inherited from OData for these types of actions. In hindsight, we probably should have always made a specific response body for all actions, but changing this now would break compatibility.

Some actions (like GenerateCSR in CertificateService) call out a specific response body, so a 204 is not expected to be used in these case. There are different schema conventions we use to show this. In JSON Schema, we created the "actionResponse" term to point to the response body format. In CSDL, this is referenced by the "ReturnType" term.

Last Edit: Jan 28, 2021 15:31:49 GMT by mraineri

siaoleio
Minnow

Posts: 11

How to determine the JSON response format? Jan 29, 2021 7:39:47 GMT

Quote

Post by siaoleio on Jan 29, 2021 7:39:47 GMT

Hi Mraineri

Thanks a lot for your response. I still have two questions:

Question 1.

When we talk about "action", does "action" means any operation (for example, http post/patch/delete) for a redfish resource?

In the future, if redfish define an patch operation which can modify the chassis's asset tag, this operation is a so called "action". So if we sent a patch request to the chassis (and we did not define the action return type), and if the respone is code 200, we can only return the "error responese" format json. And we can not return code 200 with the updated chassis format json payload.

Is this correct?

Question 2.

I want to provide a oem operation for downloading the Manager's configuration xml file.
1) Is this operation an "action"? If it is an "action", and I return 200 with a download file stream, it seems to be a wrong response.
2) I see the specification shows some info about response "ContentType"
:
---------------------------------------------------------------------------
The message body's representation type.

Services shall specify a Content-Type of application/json when returning resources as

JSON.

Services shall specify a Content-Type of application/xml when returning metadata as XML.

Services shall specify a Content-Type of application/yaml or application/vnd.oai.openapi

when returning OpenAPI schema as YAML.

Services shall specify a Content-Type of text/event-stream when returning an SSE stream.

;charset=utf-8 shall be appended to the Content-Type if specified in the chosen mediatype in the Accept header for the request.

---------------------------------------------------------------------------
It seems that there is no Content-Type of application/octet-stream, how can I provide a file download function (I am sorry I know less about SSE stream, can SSE provide download file function) ?

Thank you.

With kindest regards.

Last Edit: Jan 29, 2021 9:43:36 GMT by siaoleio

mraineri
Administrator

Posts: 1,132

How to determine the JSON response format? Jan 29, 2021 14:11:02 GMT siaoleio likes this

Quote

Post by mraineri on Jan 29, 2021 14:11:02 GMT

For your first question, no, an action does not mean any type of operation. An action is specifically a POST on an action URI to invoke an operation that doesn't translate nicely to CRUD semantics, such as invoking the "Reset" action found on a "ComputerSystem" resource. For the example you have where a client is performing a PATCH on "AssetTag", the response body for a 200 OK will contain a representation of the resource (not an error response).

For your second question, an action probably isn't the best way to do that. In the Redfish model today, we do have string properties that reference URIs that are not within the data model (for example, the "BinaryDataUri" property in "Assembly"). I would recommend making an OEM property that is a string referencing where a client can perform a GET operation to download the XML file. Since this is a string property and not a reference with "@odata.id", you're pointing outside of the data model and not strictly bound by the Content-Type values you see. So, it would look something like this in the "Manager" resource:

{
    "Id": "BMC",
    "Name": "BMC",
    ...
    "Oem": {
        "Contoso": {
            "@odata.type": "#ContosoManager.v1_0_0.Manager",
            "ConfigFile": "/redfish/v1/Managers/BMC/Oem/Contoso/config.xml"
        }
    }
}

mraineri Administrator Posts: 1,132	How to determine the JSON response format? Jan 29, 2021 14:20:53 GMT siaoleio likes this Quote Select Post Deselect Post Link to Post Back to Top Post by mraineri on Jan 29, 2021 14:20:53 GMT Also, for SSE, that is strictly for event notifications coming from the service; it's not a method for downloading general data.

Post by siaoleio on Jan 28, 2021 7:18:24 GMT

Post by mraineri on Jan 28, 2021 15:30:04 GMT

Post by siaoleio on Jan 29, 2021 7:39:47 GMT

Post by mraineri on Jan 29, 2021 14:11:02 GMT

Post by mraineri on Jan 29, 2021 14:20:53 GMT