Identity Self-Provisioning Service HTTP API

System Architecture Appendix Identity Self-Provisioning Service HTTP APIs

Document ID	uid-sys-arch
Version	1.0
Status	Release

Appendix

API Documentation

The appendix contains reference information about UniquID’s API.

Identity Self-Provisioning Service HTTP APIs

API Overview

The described API operated with structures that always in JSON format.

All responses have Content-Type: application/json

METHOD TYPE	URI	DESCRIPTION
GET	/api/v1/devices	Get list of managed devices
GET	/api/v1/devices/:status	Get list of managed devices filtered by status
GET	/api/v1/enrollment	Get list of the orchestration contracts
GET	/api/v1/enrollment/:providerAddress	Get the orchestration contract for the specified Provider Address
POST	/api/v1/enrollment	Create a new orchestration contract
GET	/api/v1/orchestrators	Get list of Orchestrators
GET	/api/v1/orchestrators/:xpub	Get info about specific Orchestrator
POST	/api/v1/orchestrators	Create a new Orchestrator
DELETE	/api/v1/orchestrators/:xpub	Delete Orchestrator
GET	/api/v1/info	Get information about imprinter
GET	/api/v1/properties	Get settings information
POST	/api/v1/properties	Upload data and saves the file on disk

Detailed APIs description

Get managed devices

The method returns all the devices managed by the current Imprinter.

• If success - method returns a json array of all the devices in the response body.

• If an exception throws during the process – then return http code 500 internal server error with the reason description of error.

Request:

Method	Request	Body
GET	/api/v1/devices

Response:

Http Code	Body	Meaning
200 OK	[ { "name": "device1", "xpub": "xpub_device_1", "creationTime": 1234567890, "recipe": "test", "retries": 0, "status": "ORCHESTRATED" }, { "name": "device2", "xpub": "xpub_device_2", "creationTime": 1234567890, "recipe": "test", "retries": 0, "status": "IMPRINTED" } ]	Success! name – name of the device xpub – public key of the device creationTime – timestamp of device creation recipe – is always "test" retries – attempts to change status from *ING to *ED status – can be CREATED, IMPRINTING, IMPRINTED, ORCHESTRATING, ORCHESTRATED
500 Internal Server Error	{ "error": "some java exception" }	Error! error – text message, describes the error reason

Get managed devices filtered by status

The method returns all the devices managed by the current Imprinter filtered by status.

• If success - method returns in the response body a json array of all the devices with the specified status.

• If an exception throws during the process – then return http code 500 internal server error with the reason description of error.

Request:

Method	Request	Body
GET	/api/v1/devices/:status

Response:

Http Code	Body	Meaning
200 OK	[ { "name":"device_name_1", "xpub":"public_key_1", "creationTime":1234567890, "recipe":"test" }, { "name":"device_name_2", "xpub":"public_key_2", "creationTime":1234567890, "recipe":"test" } ]	Success! name – name of the device xpub – public key of the device creationTime – timestamp of device creation recipe – is always "test"
500 Internal Server Error	{ "error": "some java exception" }	Error! error – text message, describes the error reason

Get enrollment (orchestration) contracts

The method returns all the orchestration contracts created by the current Imprinter.

• If success - method returns in the response body a json array of all the devices with the specified status.

• If an exception throws during the process – then return http code 500 internal server error with the reason description of error.

Request:

Method	Request	Body
GET	/api/v1/enrollment

Response:

Http Code	Body	Meaning
200 OK	[ { "name":"device_name_1", "providerAddress":"provider_address_1", "userAddress":"user_address_1", "txid":"transaction_id", "orchestratorName":"orchestrator_name_1", "xpub":"imprinter_public_key" }, { "name":"device_name_2", "providerAddress":"provider_address_2", "userAddress":"user_address_2", "txid":"transaction_id", "orchestratorName":"orchestrator_name_1", "xpub":"imprinter_public_key" } ]	Success! name – name of the device providerAddress – bip32 address of the provider userAddress – bip32 address of the provider txid – unique identifier of the transaction orchestratorName – name of the orchestrator that manage the device xpub – public key of the device
500 Internal Server Error	{ "error": "some java exception" }	Error! error – text message, describes the error reason

Get enrollment (orchestration) contract for a specific provider

The method returns orchestration contracts created by the current Imprinter for the specified device address.

• If success - method returns in the response body a json array of all the devices with the specified provider address.

• If given providerAddress doesn't exists returns http code 404 Not Found.

• If an exception throws during the process – then return http code 500 internal server error with the reason description of error.

Request:

Method	Request	Body
GET	/api/v1/enrollment/:providerAddress

Response:

Http Code	Body	Meaning
200 OK	[ { "name":"device_name_1", "providerAddress":"provider_address", "userAddress":"user_address_1", "txid":"transaction_id", "orchestratorName":"orchestrator_name_1", "xpub":"imprinter_public_key" } ]	Success! name – name of the device providerAddress – bip32 address of the provider userAddress – bip32 address of the provider txid – unique identifier of the transaction orchestratorName – name of the orchestrator that manage the device xpub – public key of the device
404 Not Found	{ "error": "Can't find contract with address" }	Error! Given providerAddress doesn't exists error – text message, describes the error reason
500 Internal Server Error	{ "error": "some java exception" }	Error! error – text message, describes the error reason

Create an enrollment (orchestration) contract

The method creates a new orchestration contract between an orchestrator and a device.

• If success - method returns http code 200 OK.

• If request body is empty – API returns http code 400 Bad request, with error description

• If an exception throws during the creation process – then return http code 500 internal server error with the error description in the response body.

Request:

Method	Request	Body
POST	/api/v1/enrollment	{ "orchestrator":"xpub_orchestrator", "device":"xpub_device" }

Response:

Http Code	Body	Meaning
200 OK		Success!
400 Bad Request	{ "error": "some java exception" }	Error! error – text message, describes the error reason
500 Internal Server Error	{ "error": "some java exception" }	Error! error – text message, describes the error reason

View orchestrators list

The method returns the list of all the orchestrators created by the current Imprinter.

• If success - method returns in the response body a json array of all the orchestrators.

• If an exception throws during the process – then return http code 500 internal server error with the reason description of error.

Request:

Method	Request	Body
GET	/api/v1/orchestrators

Response:

Http Code	Body	Meaning
200 OK	[ { "name":"orchestrator_name_1", "xpub":"orchestrator_1_public_key", "creationTime":1234567890 }, { "name":"orchestrator_name_2", "xpub":"orchestrator_2_public_key", "creationTime":1234567890 } ]	Success! name – name of the orchestrator xpub – public key of the orchestrator creationTime – timestamp of orchestrator creation
500 Internal Server Error	{ "error": "some java exception" }	Error! error – text message, describes the error reason

View orchestrator information

The method returns info about a specific orchestrator.

• If success - method returns in the response body a json array with the orchestrator information.

• If an exception throws during the process – then return http code 500 internal server error with the reason description of error.

Request:

Method	Request	Body
GET	/api/v1/orchestrators/:xpub

Response:

Http Code	Body	Meaning
200 OK	[ { "name":"orchestrator_name_1", "xpub":"orchestrator_1_public_key", "creationTime":1234567890 } ]	Success! name – name of the orchestrator xpub – public key of the orchestrator creationTime – timestamp of orchestrator creation
404 Not Found	{ "error": "Can't find orchestrator with xpub" }	Error! Given xpub doesn't exists error – text message, describes the error reason
500 Internal Server Error	{ "error": "some java exception" }	Error! error – text message, describes the error reason

Create a new orchestrator

The method creates a new orchestrator inside the current imprinter.

• If success - method returns http code 201 created.

• If an exception throws during the process – then return http code 400 bad request with the error description in the response body.

• If the xpub already exist – then return http code 409 Conflict with the error description in the response body.

• If any other exception throws during the creation process – then return http code 500 internal server error with the error description in the response body.

Request:

Method	Request	Body
POST	/api/v1/orchestrators	{ "name":"orchestrator_name", "xpub":"orchestrator_xpub" }

Response:

Http Code	Body	Meaning
201 OK	{ "name": "orchestrator_name_4", "xpub": "xpub4", "creationTime": 1534766128988 }	Success! name – name of the orchestrator xpub – public key of the orchestrator creationTime – timestamp of orchestrator creation
400 Bad Request	{ "error": "some java exception" }	Error! error – text message, describes the error reason
409 Conflict	{ "error": "Resource already exists" }	Error! error – text message, describes the error reason
500 Internal Server Error	{ "error": "some java exception" }	Error! error – text message, describes the error reason

Delete an orchestrator

The method deletes orchestrator by given xpub.

• If success - method returns http code 410 gone.

• If the xpub doesn’t exist, then return http code 404 Not found error with the error description in the response body.

• If any other exception throws during the creation process – then return http code 500 internal server error with the error description in the response body.

Request:

Method	Request	Body
DELETE	/api/v1/orchestrators/:xpub	{ "name":"orchestrator_name", "xpub":"orchestrator_xpub" }

Response:

Http Code	Body	Meaning
410 Gone		Success!
404 Not Found	{ "error": "Resource not found" }	Error! error – text message, describes the error reason
500 Internal Server Error	{ "error": "some java exception" }	Error! error – text message, describes the error reason

Get imprinter info

The method returns the information about the current Imprinter.

• If success - method returns the information about the current Orchestrator in the content body and http code 200 OK

• If the request has extra path – method returns http code 400 Bad request with "path not implemented" in the content body.

• If an exception throws during the process – then return http code 500 Internal server error with the reason description of error.

Request:

Method	Request	Body
GET	/api/v1/info

Response:

Http Code	Body	Meaning
200 OK	{ "name": "ImprinterTest", "xpub": "tpubDBYesqrK7QKqb5zD2RowX...", "topupAddress":"mrXWQAJi4Fk8Zt2MLgni...", "userBalance": 1000000000, "providerBalance": 0, "devicesCreated": 0, "devicesImprinted": 1, "devicesImprinting": 0, "devicesOrchestrated": 1, "devicesOrchestrating": 0 }	Success! name – name of the Imprinter xpub – public key of the imprinter topupAddress – address to use to recharge the Orchestrator userBalance – coin balance of the "user" bip32 hierarchy providerBalance – coin balance of the "provider" bip32 hierarchy devicesCreated – number of devices in Created status devicesImprinted – number of devices in Imprinted status devicesImprinting – number of devices in Imprinting status devicesOrchestrated – number of devices in Orchestrated status devicesOrchestrating – number of devices in Orchestrating status
400 Bad Request	{ "error": "Path not implemented" }	Error! error – text message, describes the error reason
500 Internal Server Error	{ "error": "some java exception" }	Error! error – text message, describes the error reason

View imprinter properties

The method allows to view the properties of the current Imprinter.

• If success - method returns the properties of the current Imprinter in the content body and http code 200 OK

• If an exception throws during the process – then return http code 500 Internal server error with the reason description of error.

Request:

Method	Request	Body
GET	/api/v1/properties

Response:

Http Code	Body	Meaning
200 OK	{ "network": "com.uniquid.regtest", "mqttBroker": "tcp://ipaddress:port", "mqttTopic": "ImprinterTest", "httpPort": 8090, "insightApiUrl": "http://ipaddress:port/insight-api", "registryUrl": "http://ipaddress:port", "peers": "ipaddress;ipaddress;ipaddress" }	Success! network – blockchain network (bitcoin, litecoin, …) mqttBroker – url of the mqtt broker httpPort – server listening on this port insightApiUrl – url of the insight api service registryUrl – url of the registry service peers – ip addresses of the peers
500 Internal Server Error	{ "error": "some java exception" }	Error! error – text message, describes the error reason

Upload properties file

The method allows to upload a settings file to the current Imprinter.

• If success - method returns the information about the current Imprinter in the content body and http code 200 OK

• If request body is empty – API returns http code 400 Bad request, with error description

• If an exception throws during the process – then return http code 500 Internal server error with the reason description of error.

Request:

Method	Request	Body
POST	/api/v1/properties	File to upload

Response:

Http Code	Body	Meaning
200 OK		Success!
400 Bad Request	{ "error": "some java exception" }	Error! error – text message, describes the error reason
500 Internal Server Error	{ "error": "some java exception" }	Error! error – text message, describes the error reason