20.2 Common API specifications
This section presents the specifications common to the APIs provided by JP1/IT Desktop Management 2.
Communication method
The following communication protocols and port numbers are used by APIs.
- Communication protocols
-
HTTP protocol and HTTPS protocol are supported by APIs. For both protocols, version 1.1 is supported. For the detailed specifications of the communication protocols, see the following standards:
-
HTTP protocol: RFC2616
-
HTTPS protocol: RFC2818
When HTTPS is used as the communication protocol, TLS 1.2 and SHA-2 (SHA-256) are used.
- Important
-
The SSL server certificate is necessary to use HTTPS. For details, see the JP1/IT Desktop Management 2 Configuration Guide for information on how to build an environment for using HTTPS with the external system linkage configuration.
-
- Port number
-
The port number is set to 31030 by default. To change the port number, perform a setup on the management server.
Security and authentication
To send an API request and get a response, you have to undergo user authentication.
To undergo user authentication, specify authentication information in the request header as follows:
X-ITDM-Authorization1:user-ID X-ITDM-Authorization2:password
- user-ID
-
Specify a character string generated from a Base64-encoded user ID. API permission must be assigned to the specified user ID.
- password
-
Specify a character string generated from the Base64-encoded password that corresponds to the set user ID.
I/O format
APIs use the JSON format for both requests and responses. Specify data format in the request header as follows:
Content-Type:application/json
Use UTF-8 as the character encoding.
For details about the data type of the value set in the message body of requests and responses, see the applicable description provided by respective APIs.
Request format
The request format consists of the request line, the request header, and the request message body. Specify ASCII characters in the request line and the request header. URL encoding is necessary if you specify illegal URL characters.
Format
method∆/jp1itdm/api/apiVersion/resource/other?query∆HTTP/1.1 Host:host:port Accept-Language:lang Content-Type:application/json Accept:application/json X-ITDM-Authorization1:userID X-ITDM-Authorization2:password messageBody
Item |
Category |
Description |
||
---|---|---|---|---|
Request line |
method |
Mandatory |
Specify one of the following methods:
The specifiable methods vary with each API. For details, see the applicable description provided by each API. |
|
apiVersion |
Mandatory |
Specify an API version. For details, see the applicable description provided by each API. |
||
resource |
Mandatory |
Specify a resource. The specifiable resources vary with each API. For details, see the applicable description provided by each API. |
||
other |
Optional |
If necessary, specify a value that can uniquely identify a resource or resource operation. For details, see the applicable description provided by each API. |
||
?query |
Optional |
If necessary, specify a query string. For details, see the applicable description provided by each API. |
||
Request header |
Host: |
host |
Mandatory |
Specify either the host name or IP address of the management server. |
port |
Mandatory |
Specify the port number of the management server. |
||
Accept-Language: |
lang |
Mandatory |
Specify one of the following language codes in the message of responses:
|
|
Content-Type: |
application/json |
# |
Always specify application/json. |
|
Accept: |
application/json |
Mandatory |
Always specify application/json. |
|
X-ITDM-Authorization1: |
userID |
Mandatory |
Specify a character string generated from a Base64-encoded user ID. |
|
X-ITDM-Authorization2: |
password |
Mandatory |
Specify a character string generated from the Base64-encoded password that corresponds to the set user ID. |
|
Request message body |
messageBody |
Optional |
If necessary, specify the message body in JSON format. For details, see the applicable description provided by each API. |
#:
- When method is set to GET
-
No need to specify
- In all other cases
-
Mandatory
- Important
-
Specify data within 30 MB in the request message body.
Response format
The format of a response to a request consists of the status line, the response header, and the response message body. Specify ASCII characters in the status line and the response header.
Format
HTTP/1.1∆statusCode∆statusCodeText Content-Type:application/json Cache-Control:no-store, no-cache, max-age=0 X-Content-Type-Options:nosniff messageBody
Item |
Description |
||
---|---|---|---|
Status line |
statusCode |
The status code is stored. For details, see Status codes in this section. |
|
statusCodeText |
The text of the status code is stored. For details, see Status codes in this section. |
||
Response header |
Content-Type: |
application/json |
Always return application/json. |
Cache-Control: |
no-store, no-cache, max-age=0 |
Always return no-store, no-cache, max-age=0. |
|
X-Content-Type-Options: |
nosniff |
Always return nosniff. |
|
Response message body |
messageBody |
The response data returned when an API is called is stored in JSON format. For details, see the applicable description provided by each API. In addition, when an error occurs, error information is stored in JSON format. For details, see Error information in this section. |
Status codes
The following table describes the status codes that can be contained in the response message returned following the execution of an API:
Status code |
Text of the status code |
Description |
---|---|---|
100 |
Continue |
The client can continue with the remainder of its request. |
200 |
OK |
The request ended successfully. |
206 |
Partial Content |
A partial resource is returned. |
207 |
Multi-Status |
An error occurred during the operation of multiple resources. |
300 |
Multiple Choices |
The use of multiple pages is possible. |
301 |
Moved Permanently |
The resource has permanently moved to another location. |
302 |
Found |
The resource has temporarily moved to another location. |
303 |
See Other |
The resource has moved to another location. |
304 |
Not Modified |
The requested contents have not been modified. |
400 |
Bad Request |
|
401 |
Unauthorized |
|
403 |
Forbidden |
|
404 |
Not Found |
The client attempted to access a nonexistent resource. |
405 |
Method Not Allowed |
The client attempted to access an unauthorized resource. |
406 |
Not Acceptable |
The specified data format is not supported. |
408 |
Request Time-out |
The request timed out. |
410 |
Gone |
The resource is no longer available. |
411 |
Length Required |
The client must specify the Content-Length header. |
412 |
Precondition Failed |
One or more preconditions the client specified by the If-Unmodified-Since header, the If-Matched header, or the like failed. |
413 |
Request Entity Too Large |
The message body of the request is too long. |
414 |
Request-URI Too Long |
The request line is too long. |
416 |
Requested Range Not Satisfiable |
The range specified with the Range header is out of range of the resource in question. |
417 |
Expectation Failed |
The request to extend the Expect request header field was not accepted. |
429 |
Too Many Requests |
The request was rejected because the user has sent too many requests. |
453 |
Expiration Password |
The password has expired. |
500 |
Internal Server Error |
The request could not be processed because an error occurred inside the server. |
501 |
Method Not Implemented |
The requested HTTP method is not supported. |
502 |
Bad Gateway |
The proxy server received an invalid request. |
503 |
Service Unavailable |
The service on the management server is not completely up and running. |
506 |
Variant Also Negotiates |
The server has an internal configuration error. |
512 |
License Error |
No license is registered. |
513 |
Temporary Error |
A temporary error occurred. |
514 |
JP1/Base Error |
An error occurred on the JP1/Base authentication server. |
Error information
When an API request is not successful, error information in JSON format is stored in the message body of a response and then returned. Error information has the following format.
Format
{ "errorSource":"the-URL-triggered-the-error" "message":"message", "messageID":"message-ID", "application":"jp1itdm" }
Attribute |
Data type |
Description |
---|---|---|
errorSource |
string |
The URL that triggered the error |
message |
string |
The message |
messageID |
string |
The message ID |
Example: A response returned when the user ID does not exist
HTTP/1.1 401 Unauthorized Content-Type: application/json Cache-Control: no-store, no-cache, max-age=0 X-Content-Type-Options: nosniff { "errorSource": "http://example.com:31030/jp1itdm/api/v1/objects/devices", "message": "Authentication failed. The possible causes are as follows: - The user ID or password (case-sensitive) is incorrect. - The user account is locked. You have to contact the administrator to find out if the user account is locked.", "messageID": "KDEX2016-E", "application": "jp1itdm" }
Supported data types
Set a message body of a request or response by specifying a string enclosed in double quotation marks (""). The following table describes the character string format used with each data type.
Data type |
Description |
---|---|
int |
An integer in the range -2,147,483,647 to 2,147,483,647 enclosed in "". Example: "123" |
unsigneInt |
An integer in the range 0 to 2,147,483,647 enclosed in "". Example: "123" |
long |
An integer in the range -9,223,372,036,854,775,807 to 9,223,372,036,854,775,807 enclosed in "". Example: "123" |
unsignedLong |
An integer in the range 0 to 9,223,372,036,854,775,807 enclosed in "". Example: "123" |
string |
Text data. Specify a string except control characters of ASCII characters. Any numerics specified in string-type data are treated as decimal numbers, unless otherwise specified. Example: "sample text" |
dateTime |
Specify date and time or date. In case of date and time, specify "YYYY-MM-DDTHH:MM:SS.sssZ" in UTC format.
Example of the value specified to indicate 6:52:16.000 on May 8, 2019: "2019-05-08T06:52:16.000Z" Incase of date, specify "YYYY-MM-DDT00:00:00.000Z" format. Example of the value specified to indicate May 8, 2019: "2019-05-08T00:00:00.000Z" |
Simultaneous Execution
Up to 4 APIs can be executed at the same time.