1.2.4 Request format of the API
A request format contains a URI, method, request line, and request header. The request formats to use JP1/OA's features through APIs are as follows:
- Organization of this subsection
(1) URI format
Use URIs to specify resources for API functions. A URI contains a basic URI (from <schema> to <version>) and a relative URI (<domain> and followings). Resources are identified with the relative URI (starting from <domain>).
See the following example format and URI components list:
- Format of a URI:
-
<scheme>//<host>:<port>/<application>/<version>/<domain>/<object-type>[?<query-string>]
or
<scheme>//<host>:<port>/<application>/<version>/<domain>/<object-type>/actions/[<action-identifier>[/invoke]]
In this manual, "<scheme>//<host>:<port>/<application>" may transcribe it into "baseURL".
The following list describes the URI components.
|
Item |
Description |
|---|---|
|
<scheme> |
Protocol. Specify "HTTP" or "HTTPS". |
|
<host> |
Host name or IP address of the JP1/OA host accessed from an API client. |
|
<port> |
Port number of the JP1/OA host accessed from an API client. The default port number is 22015 for HTTP, and 22016 for HTTPS. |
|
<application> |
Name of the application that provides the API functions. Specify the fixed value of "Analytics". |
|
<version> |
Your version of the API functions. For details, see the API version of each API function. |
|
<domain> |
Category of the resource specified for the API function. For details, see the list of resources managed through the API. |
|
<object-type> |
Indicates the resource or service. For details, see the list of resources managed through the API. |
|
<query-string> |
Query parameter that specifies a query parameter. This specifies a condition for reducing or sorting <object-type>. The available query parameters depend on resources. The query parameters can be in any order. For details, see the description of HQL syntax relationships and operators. |
|
<action-identifier> |
This indicates the action for the resource. |
The components and other details of URIs vary for each API function. For more information, see the descriptions of the applicable API function.
(2) Supported HTTP methods
Among the handling methods defined in HTTP, the GET, POST, PUT, and DELETE methods are supported.
The available methods depend on the resources. For details about the available methods, see the description for each API.
(3) Request Line format description
The request line consists of the following items:
Method△Request Path (URI)△Query△HTTP Version
△: Single-byte space
|
Item |
Description |
Example |
|---|---|---|
|
Method |
Request method |
GET |
|
Request Path (URI) |
Path for the resource |
/Analytics/v1/objects/Credentials |
|
Query |
Query parameters in the request |
?$query=instanceId+eq+50 |
|
HTTP Version |
String indicating the HTTP version |
HTTP/1.1 |
A request line is limited to 8,190 or fewer bytes. For request lines larger than the maximum, the status code 414 (Request-URI Too Long) is returned.
(4) Information in the request header
A request header includes a data format and the language code of the responses.
|
Header |
Description |
Specifiable value |
Required or not |
|---|---|---|---|
|
Host |
The following host information: Host name or IP address: Host name or IP address of the JP1/OA server Port number: Port number API uses to connect with JP1/OA |
Depends on the user's environments |
Optional |
|
Accept |
Data format of the response data. |
application/json |
Required |
|
Accept-Language |
Language of the response data. Specify this if with the GET, POST, or PUT method. |
ja: Japanese en: English |
Required |
|
Content-Type |
Format of the request bodies for the POST or PUT method. |
application/json |
Required |
|
Authorization |
Authentication information. |
Basic authentication: User information HSSO token: hsso token |
Required |
|
Content-Length |
The request body size as a decimal number for the POST or PUT method. |
Request body size (unit: bytes) |
Required |