API Operation Manual

1. Introduction

1.1 Purpose of this manual

Learn how to use the APIs provided by the Optimal Shared Mobility Deployment demo app.

1.2 Prerequisites

Have a FUJITSU Research Portal account.

1.3 API List

For a list of the APIs provided by the Social Digital Twin Platform, refer to the FUJITSU Research Portal as follows:

Procedure for listing APIs in FUJITSU Research Portal

Log in to the FUJITSU Research Portal and select Optimal Shared Mobility Deployment for the Social Digital Twin Platform.Select Try the API at the bottom of the page.You can browse the list of published APIs.

2. How to Run the API

2.1 Using the FUJITSU Research Portal to execute APIs

Open the API list screen, and select the API you want to execute from the API list.

Review the API specification and select Try it.

The API trial screen appears on the right side of the screen. Select Authorization flow: authorization_code because an access token is required to use the APIs provided by the Social Digital Twin Platform. Select to automatically issue an access token.

Review the request and execute the Send button to execute the API.

2.2 API execution procedure using Bash.

Issue an access token

It can be obtained from the API list screen of FUJITSU Research Portal. Similar to 2.1 Using the FUJITSU Research Portal to execute APIs, open a trial of the APIs provided by the Social Digital Twin Platform and select Authorization flow: authorization_code. Copy the generated access token from the Authorization header.

(Reference) You can also issue an access token using the manual "Issuing the API access token" [PDF] described in FUJITSU Research Portal- Documentation.
Set up variables The FUJITSU Research Portal takes advantage of the following endpoints:
```
API_GATEWAY="https://en-apigateway.research.global.fujitsu.com"
TOKEN="Bearer [Your Token Information]"
```
Example of executing API using -curl You can get it by selecting curl on the API trial screen.

API execution: When the API for acquiring the simulation list is executed

curl -X GET "${API_GATEWAY}/sdtp/api/simulations" -H "Cache-Control: no-cache" -H "Authorization: ${TOKEN}"

API execution result example

[{"id":"sim-04d53550-a0b9-4f17-aac1-70aa5ed3fcd5","name":"TEST_Silumation","createdAt":"2023-12-13T09:21:13.646Z","start":5,"end":6,"status":"finished"}]

3. Step - Perform a digital rehearsal with the specified data or city

PREPARATION

You must create the following files and information for the target city:

SUMO net file (map.net.xml.gz)
OD file that defines the movement of people (od.csv.gz)
File of the station where the scooter is to be lent/returned (stations.csv)
Simulation Condition Parameter File (condition.json)

For details on creating data, refer to Section Data Generation Manual

This chapter describes an example of executing API using 2.2 API execution procedure using Bash.

The FUJITSU Research Portal takes advantage of the following endpoints: Set the variables as follows:

API_GATEWAY="https://en-apigateway.research.global.fujitsu.com"
TOKEN="Bearer [Your Token Information]"

When the above is ready, register the file.

File Registration

Upload the map.net.xml.gz, od.csv.gz, stations.csv, and condition.json files using the registration API. Take note of the simulation ID generated after uploading the files. It will be used later when it's time to create the env.json file

curl -X POST -F "filename=map.net.xml.gz" -F "content=@map.net.xml.gz"  -H "Authorization: ${TOKEN}" -H 'Content-Type: multipart/form-data' "${API_GATEWAY}/sdtp/api/simdataAsFormData"

curl -X POST -F "filename=od.csv.gz" -F "content=@od.csv.gz"  -H "Authorization: ${TOKEN}" -H 'Content-Type: multipart/form-data' "${API_GATEWAY}/sdtp/api/simdataAsFormData"

curl -X POST -F "filename=stations.csv" -F "content=@stations.csv"  -H "Authorization: ${TOKEN}" -H 'Content-Type: multipart/form-data' "${API_GATEWAY}/sdtp/api/simdataAsFormData"

curl -X POST -F "filename=condition.json" -F "content=@condition.json"  -H "Authorization: ${TOKEN}" -H 'Content-Type: multipart/form-data' "${API_GATEWAY}/sdtp/api/simdataAsFormData"

Example results:

{"simdataId":"simdata-6fd5b0e7-dadd-4678-862e-518213383fd2"}

If the file size is large (the request size exceeds 3 MB), 2.1 Using the FUJITSU Research Portal to execute APIs is not available because the request size limit available in the portal has been exceeded. Then, please use 2.2 API execution procedure using Bash.

Create an env.json and modify the contents based on the simdataID generated when you performed the file registration.

curl -X POST -F "filename=env.json" -F "content=@env.json"  -H "Authorization: ${TOKEN}" -H 'Content-Type: multipart/form-data' "${API_GATEWAY}/sdtp/api/simdataAsFormData"

Performing Digital Rehearsals

Run the digital rehearsal start API with the simdataId of the registered env.json.

echo '{"simdataId":"simdata-0c1d8713-7477-4466-b82a-b9eafe11226c"}' | \
curl -X POST -H "Authorization: ${TOKEN}" -H Content-Type:application/json -d @- "${API_GATEWAY}/sdtp/api/simulations"

Example results:

{"id":"sim-d2ee69a1-bb6f-4821-9978-ef92176dbed8"}

Digital Rehearsal List

The digital rehearsal list acquisition API enables you to check the execution status.

curl -H "Authorization: ${TOKEN}" "${API_GATEWAY}/sdtp/api/simulations"

Example result formatting:

[
  {
    "id": "sim-ddb56e15-d07e-42d8-bc39-d22f11df4e11",
    "name": "09/06_16:58:04",
    "createdAt": "2023-09-06T07:58:15.070Z",
    "start": 5,
    "end": 12,
    "precipitation": 0,
    "status": "finished"
  },
  {
    "id": "sim-d2ee69a1-bb6f-4821-9978-ef92176dbed8",
    "name": "09/06_17:04:16",
    "createdAt": "2023-09-06T08:04:26.436Z",
    "start": 5,
    "end": 12,
    "precipitation": 0,
    "status": "error"
  }
]

Acquisition of digital rehearsal results

curl -H "Authorization: ${TOKEN}" "${API_GATEWAY}/sdtp/api/simulations/sim-ffcafba6-5bc0-432d-ab56-ae2c2757733e"

Example result formatting:

{
  "status": "finished",
  "simulation": {
    "id": "sim-ddb56e15-d07e-42d8-bc39-d22f11df4e11",
    "condition": {
      "name": "09/06_16:58:04",
      "seed": 0,
      "createdAt": "2023-09-06T07:58:15.070Z",
      ...
    },
    "resultFiles": ["output.txt," "states.txt," "current-usage.txt," "total-usage.txt," ...]
  }
}

Acquisition of Digital Rehearsal Results File

For the contents of the result file, refer to scooterInitial Deployment or Dynamic Discount in Data Generation Manual, depending on the use case for performing digital rehearsal.

curl -H "Authorization: ${TOKEN}" "${API_GATEWAY}/sdtp/api/simulations/sim-b483240d-f761-4248-8fbf-8e3bcf4da7f1/states.txt"

If you want to see the movement graphically, you can also see the API execution results in the demo app. Visit the demo app to see the simulation results.

Stop/Delete Digital Rehearsal

curl -X DELETE -H "Authorization: ${TOKEN}" "${API_GATEWAY}/sdtp/api/simulations/sim-b483240d-f761-4248-8fbf-8e3bcf4da7f1"

List of digital rehearsal data

curl -H "Authorization: ${TOKEN}" "${API_GATEWAY}/sdtp/api/simdata"

Example result formatting:

[
  {
    "simdataId": "simdata-6fd5b0e7-dadd-4678-862e-518213383fd2",
    "filename": "od.csv.gz",
    "createdAt": "2023-09-13T08:25:05.533Z",
    "metadata": {
      "tag": "od1"
    }
  },
  {
    "simdataId": "simdata-0c1d8713-7477-4466-b82a-b9eafe11226c",
    "filename": "env.json",
    "createdAt": "2023-09-06T08:04:26.574Z",
    "metadata": {
      "simname": "09/06_17:04:16"
    }
  }
]

Digital Rehearsal data metadata update

The metadata in the registration file can be updated later. A value of null deletes the key.

echo '{"scenario":"2","tag":null}' | \
curl -X PATCH -H "Authorization: ${TOKEN}" -H "Content-Type:application/json" -d @- "${API_GATEWAY}/sdtp/api/simdata/simdata-00da2bcc-f54f-440f-9095-1a0ec416f0e2/metadata"

Example results:

{"scenario":"2"}

Digital rehearsal data deletion

curl -X DELETE -H "Authorization: ${TOKEN}" "${API_GATEWAY}/sdtp/api/simdata/simdata-00da2bcc-f54f-440f-9095-1a0ec416f0e2"