Permission Management Service HTTP APIs Part1

System Architecture Appendix Permission Management Service HTTP APIs
Part 1

Document ID	uid-sys-arch
Version	1.0
Status	Release

Appendix

API Documentation

The appendix contains reference information about UniquID’s API.

Permission Management Service HTTP APIs

API Overview

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

All responses have Content-Type: application/json

METHOD	URI	DESCRIPTION
GET	/api/v1/devices	Get all managed devices
GET	/api/v1/devices/:xpub	Get info about specific device
GET	/api/v1/contracts	Get list of the access contracts
POST	/api/v1/contracts	Create new access contracts
DELETE	/api/v1/contracts/:txid	Revoke existing access contracts
GET	/api/v1/info	Returns information about orchestrator
GET	/api/v1/properties	Get orchestrator properties
POST	/api/v1/properties	Upload data and saves the file on disk
POST	/api/v1/init	Init orchestrator

Detailed API description

Get all managed devices

Required the JSESSIONID in the request cookies, user must be logged in (see: Login API)

The API returns all managed devices. User must be logged on.

• If success - API returns a JSON array of all the orchestrated devices in the response body.

• If no device found – then returns http code 404 Not found, with error description in the body.

• If the JSESSIONID is absent, incorrect or expired, then return http code 401 Unauthorized with the error description 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/HEADERS
GET	/api/v1/devices	Cookie: JSESSIONID=298zf09hf012fh2;

Response:

HTTP CODE	BODY	MEANING
200 OK	[ { "name": "device_name_1", "xpub": "public_key_1", "recipe": "test", "contracts": 1, "shared": false }, { "name": "device_name_2", "xpub": "public_key_2", "recipe": "test", "contracts": 1, "shared": false }, ... ]	Success! name – name of the device xpub – public key of the device recipe – is always "test" contracts – number of contracts involving this device, are always 1 shared – flag indicates if this is Shared Device; provided for future evolution. Always false in this version
404 Not Found	{ "error": "No devices found" }	Error! Orchestrator have no devices error – text message, describes the error reason
401 Unauthorized	{ "error": "Session expired or incorrect credentials" }	Error! The JSESSIONID is absent, incorrect or expired. error – text message, describes the error reason
500 Internal Server Error	{ stack: [ { "error": "some java exception" "trace": [ "com.uniquid.servlet..... "com.uniquid.dao..... .... ] }, { …. }, …. ] }	Error! Unexpected error. Must not appear in release version. stack – array of cascade of exceptions error – text message, describes the error reason trace – the array of strings contains java trace for error.

Get info about specific device

Required the JSESSIONID in the request cookies, user must be logged in (see: Login API)

The API returns information about the specific device.. To use this API – User must be logged on.

• If success – API returns a JSON array containing just one item in the response body.

• If there is no device with given xpub – then return http code 404 Not found with error description

• If the JSESSIONID is absent, incorrect or expired, then return http code 401 Unauthorized with the error description 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/HEADERS
GET	/api/v1/devices/:xpub	Cookie: JSESSIONID=298zf09hf012fh2;

Response:

HTTP CODE	BODY	MEANING
200 OK	{ "name":" dev_name_1", "xpub": "pub_key_1", "recipe": "test", "contracts": 1, "shared": false }	Success! name – name of the device xpub – public key of the device recipe - is always "test" contracts – number of contracts involving this device. Is always 1 shared – flag indicates if this is Shared Device; provided for future evolution. Always false in this version
404 Not found	{ "error": "Device with xpub: 'af3J42if4828c2' not found" }	Error! Orchestrator have no device with given xpub error – text message, describes the error reason
401 Unauthorized	{ "error": "Session expired or incorrect credentials" }	Error! The JSESSIONID is absent, incorrect or expired. error – text message, describes the error reason
500 Internal Server Error	{ stack: [ { "error": "some java exception" "trace": [ "com.uniquid.servlet..... "com.uniquid.dao..... .... ] }, { …. }, …. ] }	Error! Unexpected error. Must not appear in release version. stack – array of cascade of exceptions error – text message, describes the error reason trace – the array of strings contains java trace for error.

Get list of access contracts

Required the JSESSIONID in the request cookies, user must be logged in (see: Login API)

The API returns a list of all the Access Contracts of current tenant. To use this API – User must be logged on.

• If success – API returns a JSON array containing all the access contracts in the response body.

• If the JSESSIONID is absent, incorrect or expired, then return http code 401 Unauthorized with the error description 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/HEADERS
GET	/api/v1/contracts	Cookie: JSESSIONID=298zf09hf012fh2;

Response:

HTTP CODE	BODY	MEANING
200 OK	[ { "provider": { "name":"device_name_1", "xpub":"device_xpub", "address":"device_address_1" }, "user": { "name":"device_name_2", "xpub":"device_xpub_2", "address":"device_address_2" }, "revoker": { "name":"device_name_3", "xpub":"device_xpub_3", "address":"device_address_3" }, "txid":"txid", "recipe":"Access", "status":"ACTIVE", "timestamp":123456789, "functions": [34,35], "shared": false }, … ]	Success! provider – provider device information user – user device information revoker – revoker device information txid – unique identifier of the transaction recipe – is always "Access" status – status of the contract. It can be 'pending', 'active' or 'revoked' timestamp – creation time of the contract functions – functionality enabled by the "provider" to the "user" shared – flag indicates if this is Shared Contract; provided for future evolution. Always false in this version
401 Unauthorized	{ "error": "Session expired or incorrect credentials" }	Error! The JSESSIONID is absent, incorrect or expired. error – text message, describes the error reason
500 Internal Server Error	{ stack: [ { "error": "some java exception" "trace": [ "com.uniquid.servlet..... "com.uniquid.dao..... .... ] }, { …. }, …. ] }	Error! Unexpected error. Must not appear in release version. stack – array of cascade of exceptions error – text message, describes the error reason trace – the array of strings contains java trace for error.

Create new Access Contract

Required the JSESSIONID in the request cookies, user must be logged in (see: Login API)

The API creates a new Access Contract between devices provider and user. This API allows to create contract and if both devices belongs to current tenant. To use this API - User must be logged on.

• If success – API returns http code 200 OK

• If the JSESSIONID is absent, incorrect or expired, then return http code 401 Unauthorized with the error description in the response body.

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

• If provider does not exist in orchestrator database – API returns http code 404 Provider with given Xpub not found.

• If user does not exist in orchestrator database – API returns http code 404 User with given Xpub 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/HEADERS
POST	/api/v1/contracts	{ "provider":"device_xpub", "user":"device_xpub", "functions": [34,35] } "functions" is optional. If not set, then the orchestrator will allow functions 33 to 37. Cookie: JSESSIONID=298zf09hf012fh2;

Response:

HTTP CODE	BODY	MEANING
200 OK		Success!
401 Unauthorized	{ "error": "Session expired or incorrect credentials" }	Error! The JSESSIONID is absent, incorrect or expired. error – text message, describes the error reason
400 Bad request	{ "error": "Body can't be empty" }	Error! Client provide incorrect request. error – text message, describes the error reason
404 Not found	{ "error": "Provider with given Xpub not found" }	Error! There is no provider with given Xpub in database of Orchestrator error – text message, describes the error reason
{ "error": "User with given Xpub not found" }	Error! There is no user with given Xpub in database of Orchestrator error – text message, describes the error reason
500 Internal Server Error	{ stack: [ { "error": "some java exception" "trace": [ "com.uniquid.servlet..... "com.uniquid.dao..... .... ] }, { …. }, …. ] }	Error! Unexpected error. Must not appear in release version. stack – array of cascade of exceptions error – text message, describes the error reason trace – the array of strings contains java trace for error.

Delete an Access Contract

Required the JSESSIONID in the request cookies, user must be logged in (see: Login API)

The API deletes existing Access Contract. To use this API – User must be logged on.

• If success – API returns http code 200 OK

• If the JSESSIONID is absent, incorrect or expired, then return http code 401 Unauthorized with the error description in the response body.

• If contract with given txid not exist – then return 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/HEADERS
DELETE	/api/v1/contracts/:txid	Cookie: JSESSIONID=298zf09hf012fh2;

Response:

HTTP CODE	BODY	MEANING
200 OK		Success!
401 Unauthorized	{ "error": "Session expired or incorrect credentials" }	Error! The JSESSIONID is absent, incorrect or expired. error – text message, describes the error reason
404 Not found	{ "error": "Contract not found" }	Error! Resource not found. error – text message, describes the error reason
500 Internal Server Error	{ stack: [ { "error": "some java exception" "trace": [ "com.uniquid.servlet..... "com.uniquid.dao..... .... ] }, { …. }, …. ] }	Error! Unexpected error. Must not appear in release version. stack – array of cascade of exceptions error – text message, describes the error reason trace – the array of strings contains java trace for error.

Get Orchestrator info

Required the JSESSIONID in the request cookies, user must be logged in (see: Login API)

The API returns the information about the current Orchestrator. User must be logged on.

• If success – API 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 the JSESSIONID is absent, incorrect or expired, then return http code 401 Unauthorized with the error description 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/HEADERS
GET	/api/v1/info	Cookie: JSESSIONID=298zf09hf012fh2;

Response:

HTTP CODE	BODY	MEANING
200 OK	{ "name":"OrchestratorNJI95H28R4TA", "publicKey": "tpubDBYT1CEYNPzH9AveZd55....", "providerBalance":0, "userBalance":0, "topupAddress":"mkZusM4szmV7pkWYDvdVTHk28Jm..." }	Success! name – name of the Orchestrator publicKey – Orchestrator’s public key providerBalance – coin balance of the "provider" bip32 hierarchy userBalance – coin balance of the "user" bip32 hierarchy topupAddress – address to use to recharge the Orchestrator
400 bad request	Path not implemented	Error! Extra path information not permitted
401 Unauthorized	{ "error": "Session expired or incorrect credentials" }	Error! The JSESSIONID is absent, incorrect or expired. error – text message, describes the error reason
500 Internal Server Error	{ stack: [ { "error": "some java exception" "trace": [ "com.uniquid.servlet..... "com.uniquid.dao..... .... ] }, { …. }, …. ] }	Error! Unexpected error. Must not appear in release version. stack – array of cascade of exceptions error – text message, describes the error reason trace – the array of strings contains java trace for error.

Get Orchestrator properties

Required the JSESSIONID in the request cookies, user must be logged in (see: Login API)

The API allows to list the properties of the current Orchestrator. User must be logged on.

• If success – API returns the properties of the current Orchestrator in the content body and http code 200 OK

• If the JSESSIONID is absent, incorrect or expired, then return http code 401 Unauthorized with the error description 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/HEADERS
GET	/api/v1/properties	Cookie: JSESSIONID=298zf09hf012fh2;

Response:

HTTP CODE	REQUEST	MEANING
200 OK	{ "network":"", "mqttTopic":"", "mqttBroker":"", "httpPort":"", "insightApiUrl":"", "registryUrl":"", "imprinterUrl":"" }	Success! network – blockchain network mqttTopic – listening topic mqttBroker – broker for MQTT communication insightApiUrl – blockchain API service registryUrl – URL of the registry service imprinterUrl – URL of the imprinter service
401 Unauthorized	{ "error": "Session expired or incorrect credentials" }	Error! The JSESSIONID is absent, incorrect or expired. error – text message, describes the error reason
500 Internal Server Error	{ stack: [ { "error": "some java exception" "trace": [ "com.uniquid.servlet..... "com.uniquid.dao..... .... ] }, { …. }, …. ] }	Error! Unexpected error. Must not appear in release version. stack – array of cascade of exceptions error – text message, describes the error reason trace – the array of strings contains java trace for error.

Update Orchestrator properties

Required the JSESSIONID in the request cookies, user must be logged in (see: Login API)

The API allows to upload a settings file to the current Orchestrator. User must be logged on.

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

• If the JSESSIONID is absent, incorrect or expired, then return http code 401 Unauthorized with the error description in the response body.

• 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/HEADERS
POST	/api/v1/properties	File to upload Cookie: JSESSIONID=298zf09hf012fh2;

Response:

HTTP CODE	BODY	MEANING
200 OK		Success!
401 Unauthorized	{ "error": "Session expired or incorrect credentials" }	Error! The JSESSIONID is absent, incorrect or expired. error – text message, describes the error reason
400 Bad request	{ "error": "Body can't be empty" }	Error! Client provide incorrect request. error – text message, describes the error reason
500 Internal Server Error	{ stack: [ { "error": "some java exception" "trace": [ "com.uniquid.servlet..... "com.uniquid.dao..... .... ] }, { …. }, …. ] }	Error! Unexpected error. Must not appear in release version. stack – array of cascade of exceptions error – text message, describes the error reason trace – the array of strings contains java trace for error.

Init Orchestrator

No special authentication requirements for this API call

The API initialize orchestrator (set organization). This organization needs to start working orchestrator and use to communicate between another components of the system. The Init method can be called only once at the beginning. All other APIs couldn't be called before the Init call.

• If success – API returns https code 200 OK.

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

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

Request:

METHOD	REQUEST	BODY/HEADERS
POST	/api/v1/init	{ "orgId": "pepsico" }

Response:

HTTP CODE	BODY	MEANING
200 OK		Success!
403 Forbidden	{ "error": "Settings already initialized" }	Error! The Orchestrator already initialized. The second call of Init not allowed. error – text message, describes the error reason
400 Bad request	{ "error": "Body can't be empty" }	Error! Client provide incorrect request. error – text message, describes the error reason
500 Internal Server Error	{ stack: [ { "error": "some java exception" "trace": [ "com.uniquid.servlet..... "com.uniquid.dao..... .... ] }, { …. }, …. ] }	Error! Unexpected error. Must not appear in release version. stack – array of cascade of exceptions error – text message, describes the error reason trace – the array of strings contains java trace for error.