Submit Requests

Edit online

The Submit Requests operation carries out multiple Web Services API requests as specified in its request body, and returns response information in a single API response.

HTTP method and URI

POST /api/services/aggregation/submit

Request body contents

The request body is expected to contain a JSON object with the following field:

Field name	Type	Rqd/Opt	Description
`requests`	Array of api-request objects	Required	Array of api-request objects, each representing one Web Services API operation for the service to run.
`req-headers`	Array of api-header objects	Optional	Array of api-header objects, each defining an HTTP header to add or modify in the header list for every api-request in the requests array. The headers associated with the Submit Requests operation are the basis for the headers used when carrying out each api-request. Any api-header objects specified here are processed in the order provided to modify those headers, and the resulting header set is used as the basis for every api-request. If a same-named header already appears in the base set of headers, the value supplied in the api-header object will override that existing value. If a same-named header does not already appear, then the header will be added with the specified value. An api-header object with only a name field and no value field will cause that header to be omitted. Note that an HTTP request header with an empty value can be set by supplying the empty string ("") for the api-header value field. Supplying null for the value field is not permitted. Note that when comparing header names case is not taken into account. So, for example, header name "abc" is considered the same as header name "ABC". The request header names Content-Type and Accept may not be specified. Only operations which expect JSON (if they have a request body), and generate JSON (if they have a response body) are supported. Therefore, the Content-Type and Accept headers associated with Submit Requests suffice. The request header name Content-Length may not be specified. The Submit Requests operation handles any needed calculation of Content-Length for the contained requests. Note that further header modification can be specified in each api-request. Such an individual request modification overrides any modification for same-named headers specified here.
`resp-headers`	Array of String	Optional	HTTP header names. For each api-request, if the corresponding HTTP response contains any of these header names, those headers will be returned in the headers field of the corresponding api-response object in the Submit Requests response body. Note that when comparing header names case is not taken into account. So, for example, header name "abc" is considered the same as header name "ABC". Values may repeat in this array, and repeated values do not cause the headers field of the api-response objects to contain duplicates. However if a header name appears multiple times in an api-request's response, it will appear multiple times with each respective value in the headers field of the api-response. Note that, in general, response headers which are generated by the HMC API HTTP server itself, such as the Server response header, should not be expected to be seen for an individual api-response. That is because each individual api-request is not routed through the HTTP server but instead is driven as part of the Submit Requests HMC API HTTP server request. An exception to this guidance for server-generated response headers is the Date response header. If Date is requested in resp-headers it will be generated for each api-request by Submit Requests itself so that it may be returned.
`threads`	Integer (1-10)	Optional	The maximum number of threads the HMC may use to run the operations in the requests array. The default value is 1. A threads value of 1 specifies single-threaded execution. All requests will be issued on the HMC on a single thread in the same order they are specified in the requests array. A request will not be started until the previous request has completed. Single-threaded execution guarantees that the order of api-response objects in the response will match the order of the corresponding api-request objects in the requests array. A threads value greater than 1 specifies multi-threaded execution. The requests will be carried out on the HMC on multiple threads, up to the number specified. There will be no guarantee of the sequence of execution and no guarantee that any given request will be complete before another request is begun. The order of api-response objects in the response body will likewise not be predictable.

The api-request nested object contains the following fields:

Field name	Type	Rqd/Opt	Description
`method`	String	Required	The request method of the desired operation. For example, "GET", "POST", or "DELETE" (case is not significant).
`uri`	String/ URI	Required	The URI of the desired operation, including query parameters, if any.
`body`	Object	Optional	The JSON request body, if any, of the desired operation.
`req-headers`	Array of api-header objects	Optional	Array of api-header objects, each defining an HTTP header to add or modify in the header list used for this api-request only. The req-headers specified generally in the Submit Requests request body, if any, are applied first in the manner described for that field. Then these request-specific req-headers are applied to that modified base set in the same manner for this api-request only. The same guidance and restrictions given for the general req-headers field apply to this request-specific req-headers field.
`resp-headers`	Array of String	Optional	HTTP header names. For this api-request, if the corresponding HTTP response contains any of these header names, that header will be returned in the headers field of the corresponding api-response object in the Submit Requests response body. This array supplements any array specified generally in the Submit Requests request body.
`id`	String (1-64)	Optional	If an ID is provided, it will be returned in the id field of the corresponding api-response object in the Submit Requests response. Clients may use this ID to correlate api-request and api-response objects.

The api-header nested object contains the following fields:

Field name	Type	Rqd/Opt	Description
`name`	String	Required	An HTTP header name. Note that when comparing header names case is not taken into account. So, for example, header name "abc" is considered the same as header name "ABC".
`value`	String	Optional	An HTTP header value.

The largest request body accepted by this operation is 256KB. Requests with bodies that exceed this maximum are rejected with an HTTP status 413 (Request Entity Too Large) response.

Response body contents

On successful completion, the response body is a JSON array of api-response objects as described below. The response body is sent using HTTP chunked transfer encoding.

If threads is not specified in the request body, or is specified with a value of 1, then the order of the api-response objects in the response corresponds to the order of the api-request objects in the requests array of the request body. So the first api-response object represents the response to the first api-request object, and so on.

If threads is specified in the request body with a value greater than 1, then no order of the api-response objects is guaranteed.

Regardless of the value of threads, the optional id field in the api-request and api-response objects may be used by the client to correlate requests and responses.

Each api-response object contains the following fields:

Field name	Type	Description
`body`	Object	The response body of the corresponding api-request. This field is always included but if there is no response body for the corresponding api-request then the value is null.
`status`	Integer	The HTTP status code for the corresponding api-request.
`headers`	Array of api-header objects	HTTP response headers for the corresponding api-request. This array contains only headers requested using the resp-headers field (global or specific to the api-request) in the Submit Requests request body. If a requested response header did not actually appear in the api-request's set of response headers, then it is omitted from this array. If no response headers fit this criterion then this field is omitted.
`id`	String	The id of the corresponding api-request object. If no id is provided in the api-request, this field is omitted.

Description

The Submit Requests request body specifies the Web Services API operations that are to be run in aggregation as an array of api-request objects. An api-request specification includes the operation method (for example, "GET", "POST", or "DELETE" ), the operation URI, and the operation request body (if any). It may also include HTTP request header overrides in a req-headers field (in the event that those provided with Submit Requests itself are not satisfactory) and HTTP response header names in a resp-headers field (in the event that the client needs to know the value of a response header for an individual operation). Note that while you may specify these HTTP header behaviors for an individual operation in an api-request, you may also alternatively or additionally specify these HTTP header behaviors for every operation being aggregated. So, for example, if the client needs to receive the value of the Location response header for every operation, the resp-headers field does not need to be specified repeatedly in each api-request; the resp-headers field may be specified once as a peer to the requests array and it will apply to every api-request.

The Submit Requests response is an array of JSON objects, one for each API request specified in the request body. These JSON objects include the individual request's response body (if any) and status code. Optionally, they also include HTTP response headers associated with the individual request and an id that can be used to correlate that JSON object with the matching submitted request.

Note that only operations which expect JSON (if they have a request body), and generate JSON (if they have a response body) are supported for aggregation by Submit Requests. So operations that have request bodies that are not JSON (such as Mount ISO Image) and operations that have response bodies that are not JSON (such as Get Metrics) are not supported.

Single-threaded execution may be specified with a value of 1 for the threads field in the request body, or by omitting the threads field from the request body. Under single-threaded execution, Submit Requests processes the requests sequentially in the order provided. It ensures each request has completed before beginning the next request (although some requests may initiate asynchronous jobs if they are so-specified). In other words, all of the requests are processed by the HMC on a single thread. Therefore the JSON objects in the response are in the same order as the requests in the request body.

Multi-threaded execution may be specified with a value greater than 1 for the threads field in the request body. Under multi-threaded execution, Submit Requests may process the requests in any order and their processing may overlap on up to the number of threads specified. Therefore, multi-threaded execution should not be specified if the sequence of execution of the requests is significant, or if there is some other reason why two or more of the requests should not be run simultaneously. Since the response order is not guaranteed, the client must use the id fields of api-request and api-response, or some other field unique to each expected response, to correlate the requests and responses.

Under both single-threaded and multi-threaded execution, requests are processed without regard to the result of any other request specified in the Submit Requests request body. Therefore, exercise caution aggregating requests with inter-dependencies. Even under single-threaded execution where it is guaranteed that request N has completed before request N+1 is initiated, it is not guaranteed that request N has completed successfully before request N+1 is initiated.

The response is returned using HTTP chunked transfer encoding, which allows the HMC to stream the response to each request as it completes, rather than having to accumulate the responses to all aggregated requests before returning data.

Authorization requirements

This operation has no authorization requirements of its own and will not directly report any authorization error.

The operation in each api-request is subject to that operation's authorization requirements as if it had been issued individually from the same API session. Any authorization problem is reflected in the status and/or body fields of the corresponding api-response object with the same content that would have been in the HTTP status code and response body had the request been issued directly and individually.

HTTP status and reason codes

On success, HTTP status code 200 (OK) is returned and the response body is provided as described in Response body contents.

It is important to recognize that a successful status code from Submit Requests does not indicate that every (or, indeed, any) submitted request was successful. Each api-response object must be examined to determine the outcome of each submitted api-request.

The following HTTP status codes are returned for the indicated errors, and the response body is a standard error response body providing the reason code indicated and associated error message.

Table 1. Submit Requests: HTTP status and reason codes
HTTP error status code	Reason code	Description
400 (Bad Request)	Various	Errors were detected during common request validation. See Common request validation reason codes for a list of the possible reason codes.
400 (Bad Request)	7	The request body attempted to use a req-headers field to modify one of the following request headers :Content-Type, Accept, or Content-Length.

Additional standard status and reason codes can be returned, as described in Invoking API operations.

Example HTTP interaction

Figure 1. Submit Requests: Request

POST /api/services/aggregation/submit HTTP/1.1
x-api-Session:  59ott72ftvzxkj7fz7g4jl48gh6csq7a7q3l98lm6gicq8wrl5
content-type: application/json
content-length: 257
{
   "requests":
	[
		{"id": "100000",
		 "uri": "/api/console/users?name=stevef",
		 "method": "get"},
		{"method": "DELETE",
		 "uri": "/api/services/metrics/context/no-such-animal", 
		 "id": "200000"}
	],
   "threads": 1,
   "req-headers": [{"name": "new-hdr", "value": "new-value"}]
}

Figure 2. Submit Requests: Response

200 OK
transfer-encoding: chunked
server: Hardware management console API web server / 2.0
cache-control: no-cache
date: Fri, 06 Apr 2018 15:08:04 GMT
content-type: application/json
[
	{
		"body":{"users":[{"name":"stevef","object-uri":"/api/users/a8ce7ac6-39ab-
                11e8-b4d7-00106f0d5d80","type":"standard"}]},
		"status":200,
		"id":"100000"
	},
	{
		"body":{"http-status":404,"reason":1,"request-uri":"/api/services/metrics/
                context/no-such-animal","request-method":"DELETE","message":"Context 
                specified is not found, id is not a number","request-headers":{"new-hdr"
                :"new-value","content-length":"0","host":"127.0.0.1:6794","content-type"
                :"application/json","x-api-session":
                "59ott72ftvzxkj7fz7g4jl48gh6csq7a7q3l98lm6gicq8wrl5",
                "accept-encoding":"identity","accept":"application/json"},"request-body"
                :{},"request-authenticated-as":"acsadmin"},
		"status":404,
		"id":"200000"
	}
]

Usage notes

Note that specifying a higher number for threads in the request body will not necessarily lead to better performance. One reason is that a larger number of threads may increase the contention for access to the connection which delivers completed results to the client. The relative performance of different numbers of threads is largely dependent on attributes of the individual requests, making it impossible to recommend an ideal number of threads for all applications.

For example, it has been observed that for some large collections of quick-running requests, a thread count of 2 consistently provided better overall performance than either higher thread counts or single-threaded operation. Longer running requests that use different resources may see different results. Other processing load will of course influence performance as well. This variation is why Submit Requests allows the client to tune the maximum number of threads used.

Note further that increasing the number of threads for Submit Requests may increase the possibility of one or more of the constituent requests reporting a 503 (Service Unavailable) error with reason code 3. This error is reported when exceeding the number of concurrent API requests that are allowed, either for a given user or overall for an HMC. On its own, a single Submit Requests request will not exceed these limits, even if the maximum value of threads is specified. However, if there is other concurrent API activity, from the same client or other clients, then recognize that each thread running the constituent requests for Submit Requests counts individually toward the concurrent API request limits.

In summary, if multi-threaded behavior is desired, then the client application should specify the smallest number for threads that is observed to provide the desired performance most of the time. If in doubt, or if performance is not critical, defaulting to the single-threaded behavior is recommended.