http://localhost:50000/fusionplace/api/1.2/requests
Web-API Guide
This manual is in pilot operation.
|
- Web-API Guide
- What is the Web-API?
- What You Can Do with the Web-API
- Environments Where the Web-API Can Be Used
- How to Call the Web-API
What is the Web-API?
[Web-API] is an application programming interface (API) for developing programs that use the features of fusion_place. Since [Web-API] is based on the HTTP protocol, it can be used from a variety of programs regardless of the development language.
Note that the following explanation of [Web-API] assumes basic knowledge of the HTTP protocol.
What You Can Do with the Web-API
With [Web-API], you can perform the same operations as the Requester, as shown below:
The format for making requests via [Web-API] is almost identical to the request file format used by the Requester. In fact, the Requester uses [Web-API] to send requests and receive responses from fusion_place.
Environments Where the Web-API Can Be Used
You do not have to be on the fusion_place server itself. If a computer can access the fusion_place server via URL [1], it can perform processing via [Web-API].
(fusion_place < 14.0) [Web-API] uses cookies for exchanging session information, so clients must support cookies. |
How to Call the Web-API
To use [Web-API], send the request as XML-format text data using POST to the API URL of fusion_place. The server will execute the requested process and return the result (response) also as XML-format text data.
API URL
The API URL is the fusion_place server URL with /api/1.2/requests
appended. For example, if the fusion_place server URL is http://localhost:50000/fusionplace
, the API URL will be:
Authentication (fusion_place >= 14.0)
HTTP access to [Web-API] uses Bearer authentication. Obtain an access token (ACCESS_TOKEN
) in advance and add the following Authorization
header to your HTTP request:
Authorization: bearer <ACCESS_TOKEN>
How to Obtain an Access Token
First, register the client to obtain the client credentials (CLIENT_CREDENTIALS
).
URL |
|
Method |
|
Header |
|
Body |
Specify the client name for [Web-API] in |
Response |
Concatenate |
Next, use the obtained client credentials to get the access token.
URL |
|
Method |
|
Header |
Specify the obtained client credentials in |
Body |
Specify the user account name for |
Response |
The value of |
Notes
The access token has an expiration time. When it expires, you need to obtain a new one.
URL |
|
Method |
|
Header |
Specify the obtained client credentials in |
Body |
Specify the obtained refresh token in |
Response |
|
After using the access token, be sure to terminate it explicitly.
URL |
|
Method |
|
Header |
Specify the obtained client credentials in |
Body |
Specify the obtained access token in |
Response |
Authentication (fusion_place < 14.0)
WWW-Authenticate: Digest realm="FusionPlace System",qop="auth",nonce="978cfd86321e50711213062f4573b9e7"
In HTTP access using [Web-API], the authentication method configured on the fusion_place server is used, just like with other client programs such as [Browser]. The default is Digest authentication [2]. Therefore, client programs that request processing from the fusion_place server using [Web-API] must support the configured authentication method. Most programming languages offer libraries that readily support Digest or Basic authentication.
Digest/Basic authentication uses "realms" to define the scope of user management. The realm for fusion_place is FusionPlace System
.
Also note that [Web-API] is considered a "client program" as defined in the fusion_place License Agreement. Therefore, the provision in the License Agreement or Terms of Use that limits one session (from login to logout or until the program ends) per client program per user account also applies to [Web-API].
HTTP Methods
HTTP methods (commands used to request processing or data from a server via HTTP protocol) include GET
, PUT
, and POST
, but always use POST
for [Web-API] in fusion_place.
HTTP Request (Normal Request)
Request Headers
Set the following HTTP headers as needed.
HTTP Header | Required | Description |
---|---|---|
Content-Type |
No |
If specified, use |
Content-Encoding |
No |
If specified, use |
Accept-Encoding |
No |
If specified, use |
Accept-Language |
No |
Language for the response. Use Languages other than Japanese or English will be replaced with English. |
Accept-Charset |
No |
Character set for the response. Only the first value is recognized; additional values are ignored. If omitted, |
Authorization |
Yes |
Specify the access token as |
Request Body
The request body should be in the following text format:
<?xml version="1.0" encoding="Windows-31J"?> (1)
<request type="IMPORT_VALUES" desc="Import Actuals A"> (2)
<!-- ... -->
</request> (3)
1 | XML declaration |
2 | Start of "request" |
3 | End of "request" |
While the format is similar to that used when using the Requester, note the following differences:
-
With the Requester, multiple requests can be included in one request file, but [Web-API] allows only one request (the range enclosed by the
request
tag) per HTTP request. Therefore, the enclosingrequests
tag is not used in [Web-API]. -
Features available in the Requester such as embedding environment variable values and external mode are not supported in [Web-API].
Aside from these differences, write the request in the same way as for the Requester.
HTTP Request (Session Initialization Request)
In some cases, you may want to perform authentication and establish a session before sending a request. This is typically needed when using "Chunked Transfer Encoding (CTE)", introduced in HTTP/1.1, for data transmission.
CTE is convenient for transmitting large data because it eliminates the need to specify the data length in the HTTP header (Content-Length
). However, some clients, such as the Java HttpUrlConnection
API, do not support authentication when using CTE.
In such cases, you should first send a request that includes a request body without using CTE. After authentication is completed in the first request, you can then send normal requests using CTE, as authentication will no longer be required.
HTTP Response
HTTP Status Code
Standard-compliant HTTP response codes are returned based on the processing result. For example, if there are no communication issues with the server, 200 OK
is returned. Note that 200 OK
only indicates successful communication with the server—it does not imply that the request was processed successfully without errors or warnings. To determine the success of the request, check the "result code" in the response body.
Response Body
For responses to session initialization requests, there is no response body.
For normal requests, the response body should be as follows:
<?xml version="1.0" encoding="Windows-31J"?> (1)
<response type="IMPORT_VALUES" desc="Import Actuals A"> (2)
<!-- ... -->
</response> (3)
1 | XML declaration |
2 | Start of "response" |
3 | End of "response" |
Just like in the request body, only one response (the range enclosed by the response
tag) is included in a single HTTP response. Therefore, the enclosing responses
tag is not used in [Web-API].
Other than that, the same rules as the Requester response files apply.