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: GET POST PUT DELETE 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.
	Host:	`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: `ja` Japanese `en` English `zh` Simplified Chinese
	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.
Status line		`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	The argument is invalid. The request format is incorrect.
401	Unauthorized	An ID or password has not been specified. The specified ID or password is incorrect. The account is locked.
403	Forbidden	The client does not have the permission to execute the resource. The user does not have the API permission.
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`-`DD`T`HH`:`MM`:`SS`.`sss`Z" in UTC format. `YYYY` Specify four digits for the year. `MM` Specify two digits for the month. `DD` Specify two digits for the date. `HH` Specify two digits for the hour. `MM` Specify two digits for the minute. `SS` Specify two digits for the second. `sss` Specify three digits for the millisecond. 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`-`DD`T00: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.

To Page Top