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
{
"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.
{
"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
{
"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
{
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.
\[
{
"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
{
"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.
{
"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.
{
"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.
|