rest_api.md

March 10, 2026 ยท View on GitHub

REST API

The REST API offered by onomondo-eim is a powerful interface to manage a fleet of eUICCs. The REST API lets the user trigger profile downloads and offers full access to all PSMOs and eCOs that are specified in GSMA SGP.32.

Facilities

The REST API is divided up into so called "facilities". The facility identifier is the first path element of the HTTP URL. There are four facilities defined:

  • download: management of profile downloads
  • psmo: Profile State Management Operations (PSMO)
  • eco: Eim Configuration Operations (eCO)
  • edr: eUICC data request (see also GSMA SGP.32, section 2.11.1.2)
  • euicc: eim-local eUICC configuration Operations

The purpose of the facilities is to provide separation at URL level. This allows for easier filtering to restrict access for specific REST API users.

Operations

The REST API defines four different basic operations. The name of the operation is the second path element of the HTTP URL:

  • create: create a rest resource, returns a resourceId
  • lookup: lookup a rest resource by its resourceId, returns JSON
  • delete: delete a rest resource by its resourceId, returns JSON
  • list: list all resourceIds available for the current facility, returns JSON.

ResourceId

When a REST resource is created, a so called resourceId is returned by the REST API. The resourceId uniquely identifies a REST resource and has to be memorized by the REST API user to perform further operations.

Example: URL with selected facility download and operation lookup on the resourceId "8a901bd9-f203-4eae-bcba-12dee32f4444"

http://127.0.0.1:8080/download/lookup/8a901bd9-f203-4eae-bcba-12dee32f4444

Interface

The REST API receives JSON formatted data via HTTP POST requests and returns a JSON formatted response. The following chapter describes how the REST interface works in general.

Creating Orders

Each request contains a so called resource. The resource is a JSON formatted request that contains the eidValue and a so called order. The eidValue identifies the eUICC and the order contains specific parameters that the eIM needs to fulfill a specific task (e.g. trigger a profile download).

Example: Rest resource that orders to trigger a profile download

{ "eidValue" : "89882119900000000000000000000005", "order" : {"activationCode" : "1$rsp.example.com$EXAMPLE"}}'

Monitoring Orders

The REST API user is expected to poll the rest resource from time to time to check on its status. The polling is done using the lookup operation:

Example: URL to lookup a specific REST resource

http://127.0.0.1:8080/download/lookup/8a901bd9-f203-4eae-bcba-12dee32f4444

The result will contain a status field along with some other information that allows the REST API user to monitor the progress and the outcome of the current order.

The following fields are defined:

  • status: contains the processing status of an order. This field does not say anything about success or failure of an order. It just tells the processing status. When an order is new, the status will be new. An order that is currently in progress will report work as status. When the order is finished, the reported status will be done. In case of an REST resource error (non existing resourceId) the status will be absent. A REST resource that has just been deleted will report deleted to confirm its deletion. Contrary to all other fields, the status field is a mandatory field that is always present.
  • timestamp: contains the timestamp of the last update. The timestamp may be used by the REST API user to determine how long orders take.
  • resource: The resource is a copy of the JSON object that was submitted when the REST resource was created. It contains the eidValue and the order. It is included in the data so that the REST API user does not have to memorize it.
  • outcome: The outcome depends on the facility and on the specific order. Its purpose is to inform the REST API user of the order results. The outcome is modeled as a list since an outcome may contain more then one result. This is in particular true for eUICC packages with more than one PSMO or eCO. The outcome is also used to convey error codes back to the REST API user in case there were problems during the execution of the order.
  • debuginfo: The debuginfo contains the last ESipa message that was received from the IPAd in erlang ETF format. During normal operation the field has no relevance. Its only purpose is to provide debug information to a software engineer. It should also be noted that the structure of the contents of this field may changed without further notice.

Example: A typical lookup response after a successful profile install:

{"status": "done", "timestamp": "1718881629", "resource": {"eidValue": "89086030202200000022000027485428", "order": {"download": {"activationCode": "1$rsp.example.com$EXAMPLE"}}}, "outcome": [{"profileInstallationResult": {"finalResult": "successResult", "iccid": "984474680000730771F0"}}], "debuginfo": "83680264001370656E64696E674E6F74696669636174696F6E680264001970..."}

Example: A typical lookup response when an invalid resourceId is used:

{"status": "absent"}

Deleting REST resources

The REST API user is responsible to keep the rest table clean. When an order is done or has to be revoked for some reason, the REST API user will use the delete operation to remove the related REST resource from the rest table.

Example: URL to delete a specific REST resource

http://127.0.0.1:8080/download/delete/8a901bd9-f203-4eae-bcba-12dee32f4444

The eIM will confirm the deletion of the REST resource by responding with a status deleted.

Example: A typical delete response

{"status":"deleted"}

In case the API user forgets to delete the REST resource for some reason, the REST resource it will not stay in the database indefinitely. After some generous timeout, the eIM will automatically delete the REST resource from the REST table. However, the intention behind this mechanism is to guard against database memory leaks and is not intended to be used as the general mechanism to get rid of REST resources that are no longer used.

Listing REST resources

The REST API user has to keep track of his REST resources. However, there may be circumstances where the REST API user must recover his state. In this case it is possible to list all resourceIds of all REST resources that are currently in the rest table.

Example: URL to list all REST resources available in the download facility

http://127.0.0.1:8080/download/list

The eIM will respond with a resourceIdList. The REST API user may then use this list to lookup the state of each REST resource. Since the list only contains the resourceIds of the current facility, the REST API user must repeat the process for all facilities.

Example: A typical list response with three resourceIDs

{"resourceIdList": ["2100f52e-83e1-4fed-9d30-f309daf3391a","35074412-654b-4d7b-aec0-e159837b998f","9d6b14df-1875-4827-8236-916383972a19"]}

eIM Information

The REST API also features an info page which can be used by the REST API user to gain some basic information of the eIM that it is working with. The info page mainly reflects the eIM configuration applied in sys.config (see also section "Configuration").

When an eIM is added to the eimConfiguration on the eUICC (either via ES10b:AddInitialEim or via addEim eCO) the data is required to be passed in its ASN.1 encoded form. To simplify the process onomondo-eim also presents the eIM configuration in two different ASN.1 encoded formats:

  • addInitialEimRequest: This data format can be passed directly to an eUICC via an ES10b APDU. It will create the eIM configuration on the eUICC so that the eUICC is associated with the current onomondo_eim instance. The eUICC will create an associationToken in response, which should be passed back to the eIM via the REST API on the euicc facility. However, on a virgin eUICC the associationToken will be 1, which is also the default onomondo-eim will use. (see also GSMA SGP.32, section 3.5.2.1)

  • eimConfigurationData: This data format has the same contents as addInitialEimRequest, but withut an envelope. This format is suitable to be used for adding the eIM to the eUICC remotely via an eCO. (see also GSMA SGP.32, section 3.5.1.1)

Example: URL that returns the eIM information

http://127.0.0.1:8080/

JSON Schema

This description above describes only the basic concept of the REST API. To give a system integrator a detailed overview on how the requests/responses should look like three JSON schema files are shipped with onomondo-eim:

  • contrib/rest_api_resource_schema.json: This schema describes a REST resource. This is the format that the requests issued to the REST API should have.

  • contrib/rest_api_response_schema.json: This schema that describes the JSON formatted response that is received from the REST API when the lookup operation is performed.

  • contrib/rest_api_info_schema.json: This schema that describes the JSON formatted info page that is received when the REST API is called without any parameters.