Hitachi

JP1 Version 12 JP1/Integrated Management 2 - Manager Command, Definition File and API Reference


5.2.3 Request format

To access the functionality provided by the Intelligent Integrated Management Base through the API, compose a request as follows:

method /application/component/apiVersion/resourceId?query httpVersion
requestHeader
 
messageBody

The following table describes how to compose a request.

Table 5‒2: Request format in detail

Item

Description

method

Specify how to operate the resource. Select a method appropriate to the API processing. The API supports the following methods:

  • GET

    Gets a list of resources or their information.

  • POST

    Enables the Intelligent Integrated Management Base to process the resource.

  • PUT

    Updates a list of resources or their information.

  • DELETE

    Deletes a list of resources or their information.

For details on the method you specify, see Format for each API.

application

The name of the application that provides the API. Always set this to im.

component

The component name of the API. Always set this to api.

apiVersion

The API version. Always set this to v1.

resourceId

The functions provided by the Intelligent Integrated Management Base can be identified by specifying a resource identifier in an API request. Specify the identifier of a function that you want to run. For details, see Table 5-3 Resource identifiers.

query

The query string. You can add search conditions to a request to filter or sort records to be returned in a response.

httpVersion

The version of the communication protocol that the API uses. Always set this to HTTP/1.1.

requestHeader

Specify the data format, language code, and other settings of the response. For details, see Table 5-4 Request headers.

messageBody

Specify the data format of the message body.

You can use the JSON format. The data is encoded in UTF-8.

Table 5‒3: Resource identifiers

Resource identifier

Resource to be accessed

nodes

Management nodes

status

Status information

links

Link information (relationship of jobnets or others)

events

JP1 events

actions

Plug-in actions (getting performance information or others)

login

Login token or permissions

proxyUsers

Proxy user information

Table 5‒4: Request headers

Header

Description

Default value

Required/Optional

Authorization

Specify the authentication information for the API. This must be specified if permission is required for the user to invoke the API.

For details on the authentication information and how to set the authentication information to invoke the REST API, see Authentication methods for REST API.

None

Required

Accept-Language

Specify the language you want to use in response data with one of the following language codes:

  • ja or ja-JP

    Japanese

  • en

    English

Omitting this header or specifying any value other than acceptable values causes en to be used.

The status code 200 is returned regardless of the specified value.

en

Optional

Content-Type

The data format of the request message body.

Omitting this header when using the POST method or specifying an invalid value results in the status code 415 to be returned.

If you use the POST method and there is no message body, or if you use the GET method and you specify a value other than application/json, the status code 200 is returned.

None

Required

Content-Length

Specify the length of the message body in the request.

  • For the GET method:

    Omit this header or specify 0.

  • For the POST method:

    Specify the size (in bytes) of the request body. This must be specified as a decimal number.

Omitting this header when using the POST method is results in the status code 411 to be returned.

If you use the POST method and you have specified the request body of which the size exceeds the specified size, the status code 500 is returned. If you use the POST method and there is no message body, or if you use the GET method, the status code 200 is returned.

None

  • Optional

    GET method

  • Required

    POST method

Accept

The data format of the response message body. Always set this to application/json.

if you use the POSTmethod and you specify a value other than application/json, the status code 406 is returned.

If you use the POST method and there is no message body, or if you use the GET method and you specify a value other than application/json, the status code 200 is returned.

application/json

Optional

Cookie

If you issue REST API requests consecutively without logging in again, specify cookie information for login API responses.

Specifying cookie enables the session to be maintained, eliminating the need to log in or out every time you issue a REST API request. The session is discarded automatically three minutes after the last REST API request is issued.

If you do not want to maintain the session, you do not have to specify this header.

In addition, do not specify it if you use authentication (Basic authentication) with login information added to a REST API.

None

Optional

If you specify a property that is not listed in the table above, the property is ignored.