Web-API Guide

« Requester | fusion_place Runtime Environment (FRE) »

This manual is in pilot operation.

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:

http://localhost:50000/fusionplace/api/1.2/requests

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

http://localhost:50000/fusionplace/rest/v1/oauth/client

Method

POST

Header

Content-Type: "application/json"

Body

{
    "grant_types": ["password", "refresh_token"],
    "scope": "webapi",
    "client_name": "<CLIENT_NAME>"
}

Specify the client name for [Web-API] in <CLIENT_NAME>.

Response

{
    "grant_types": [
      "password",
      "refresh_token"
    ],
    "client_secret_expires_at": "1718069506982",
    "scope": "webapi",
    "client_secret": "kb6WPe5XLvo6rX81btvx",
    "client_id_issued_at": "1717983106982",
    "client_name": "curl",
    "token_endpoint_auth_method": "client_secret_basic",
    "client_id": "8447d19d-5006-41d8-bb8d-9a0150c84b22"
}

Concatenate client_id and client_secret with a colon and encode it in Base64. The resulting value becomes the CLIENT_CREDENTIALS for the authentication header in the next step.

Next, use the obtained client credentials to get the access token.

URL

http://localhost:50000/fusionplace/rest/v1/oauth/token

Method

POST

Header

Content-Type: "application/x-www-form-urlencoded"
Authorization: "Basic <CLIENT_CREDENTIALS>"

Specify the obtained client credentials in <CLIENT_CREDENTIALS>.

Body

username=<USER_NAME>&password=<PASSWORD>&grant_type=password&scope=webapi

Specify the user account name for <USER_NAME> and the password for <PASSWORD>.

Response

{
    "access_token": "AKcmWdbpeX75AZi",
    "refresh_token": "3ZzboNpzcmBUrLU",
    "scope": "webapi",
    "token_type": "Bearer"
}

The value of access_token is the access token. The value of refresh_token is the refresh token, which is used to obtain a new access token when the original expires.

Notes

The access token has an expiration time. When it expires, you need to obtain a new one.

URL

http://localhost:50000/fusionplace/rest/v1/oauth/token

Method

POST

Header

Content-Type: "application/x-www-form-urlencoded"
Authorization: "Basic <CLIENT_CREDENTIALS>"

Specify the obtained client credentials in <CLIENT_CREDENTIALS>.

Body

refresh_token=<REFRESH_TOKEN>&grant_type=refresh_token

Specify the obtained refresh token in <REFRESH_TOKEN>.

Response

{
    "access_token": "QJB874KGFybPNfD",
    "refresh_token": "1NpHLSSFCwruIlW",
    "scope": "webapi",
    "token_type": "Bearer"
}

After using the access token, be sure to terminate it explicitly.

URL

http://localhost:50000/fusionplace/rest/v1/process/terminate

Method

POST

Header

Content-Type: "application/x-www-form-urlencoded"
Authorization: "Basic <CLIENT_CREDENTIALS>"

Specify the obtained client credentials in <CLIENT_CREDENTIALS>.

Body

token=<ACCESS_TOKEN>

Specify the obtained access token in <ACCESS_TOKEN>.

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

HTTP Header	Required	Description
Content-Type	No	If specified, use `application/xml`.
Content-Encoding	No	If specified, use `gzip`. In that case, the request body must be gzip-compressed.
Accept-Encoding	No	If specified, use `gzip`. The response body will be gzip-compressed.
Accept-Language	No	Language for the response. Use `ja` for Japanese or `en` for English. Only the first value is recognized; additional values are ignored. If omitted, the server’s default language is used. 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, `UTF-8` is used.
Authorization (fusion_place >= 14.0)	Yes	Specify the access token as `Bearer <ACCESS_TOKEN>`.

Content-Type

If specified, use application/xml.

Content-Encoding

If specified, use gzip. In that case, the request body must be gzip-compressed.

Accept-Encoding

If specified, use gzip. The response body will be gzip-compressed.

Accept-Language

Language for the response. Use ja for Japanese or en for English. Only the first value is recognized; additional values are ignored. If omitted, the server’s default language is used.

Languages other than Japanese or English will be replaced with English.

Accept-Charset

Character set for the response. Only the first value is recognized; additional values are ignored. If omitted, UTF-8 is used.

Authorization
(fusion_place >= 14.0)

Yes

Specify the access token as Bearer <ACCESS_TOKEN>.

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 enclosing requests 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.

Request Headers

(Same as for normal requests)

Request Body

The request body should be the following text:

<?xml version="1.0" encoding="Windows-31J"?> (1)
<connect/>

1	XML declaration

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.

1. This refers to a computer that can connect to the fusion_place server using fusion_place Manager/Browser or Excel-Link.

2. When using Single Sign-On (LDAP), the authentication method becomes Basic.