Identity

Definition

Variables in single quotes '...' can or must be changed according to your specific case.

public_key is the public key of an identity.

name is the name of an identity.

newname is the new name of an identity for the rename request.

subsystem is a subsystem, e.g. namestore.

Identity

An identity consists of a public key and a name. An identity can be assigned to a subsystem. Each subsystem can only have one default identity.

Error Response

An error response is sent in the JSON format: {"error":"*error_description*"}

Following numbers are added for references inside the documentation only.

Error descriptions are:

Nr. Error Description           - Explanation
1)  Unknown Error               - Error is not specified
2)  No identity found           - Identity was not found with given name, public key or no identity was found at all
3)  Missing identity public key - Identity public key length is zero
4)  Missing identity name       - Identity name length is zero
5)  Missing subsystem name      - Subsystem name length is zero
6)  No data                     - No JSON data given
7)  Data invalid                - Wrong JSON data given
8)  Rename failed               - Rename request failed due to wrong name, etc.
9)  Setting subsystem failed    - Setting the subsystem for an identity failed (usually this error does not occur)

Error 1) is always possible and is not listed in following requests.

ATTENTION: Any error message from the Identity API (not REST API) can occur and can be returned in the error response. These responses are not listed here.

Response Code

A response of a message has a HTTP response code. Usually, this code is 200 OK for a successful response. The code changes in some cases:

a) 200 OK         - Normal response (but may contain an error message)
b) 201 Created    - Success after POST request
c) 204 No Content - Success PUT or DELETE request
d) 404 Not Found  - Identity is not found with identifier
e) 409 Conflict   - PUT or POST request not possible due to existing duplicate

d) 404 Not Found is always used when the error message is either 2), 3) or 4).

Requests

GET Requests

Title	Returns all identities with name and public key
URL	/identity/all
Method	GET
URL Params	none
Data Params	none
Success Response	[{“pubkey”:”public_key”, “name”:”name”},…]
Error Response	{“error”:”error_desc”} 2
Attention	The response in this request is an array!

Title	Returns only a specific identity
URL	/identity/pubkey/'public_key' or /identity/name/'name'
Method	GET
URL Params	none
Data Params	none
Success Response	{“pubkey”:”public_key”, “name”:”name”}
Error Response	{“error”:”error_desc”} 2; 3 or 4

Title	Returns default identity for specific subsystem
URL	/identity/subsystem/'subsystem'
Method	GET
URL Params	none
Data Params	none
Success Response	{“pubkey”:”public_key”, “name”:”name”}
Error Response	{“error”:”error_desc”} 2; 5

POST Request

Title	Creates an identity
URL	/identity
Method	POST
URL Params	none
Data Params	{“name”:’name’}
Success Response	Response Code: :literal:` b) 201 Created`
Error Response	{“error”:”error_desc”} 6; 7 or Response Code: e) 409 Conflict if name in use

PUT Request

Title	Changes name of identity
URL	/identity/pubkey/'public_key' or /identity/name/'name'
Method	PUT
URL Params	none
Data Params	{“newname”:’newname’}
Success Response	Response Code: c) 204 No Content
Error Response	{“error”:”error_desc”} 2; 3 or 4; 6; 7; 8 or Response Code: e) 409 Conflict if newname in use

Title	Sets identity as default for a subsystem
URL	/identity/subsystem/'name'
Method	PUT
URL Params	none
Data Params	{“subsystem”:’subsystem’}
Success Response	Response Code: c) 204 No Content
Error Response	{“error”:”error_desc”} 2; 4; 6; 7; 9

DELETE Request

Title	Deletes specific identity
URL	/identity/pubkey/'public_key' or /identity/name/'name'
Method	DELETE
URL Params	none
Data Params	none
Success Response	Response Code: c) 204 No Content
Error Response	{“error”:”error_desc”} 2; 3 or 4

OPTIONS Request

Title	Gets request options
URL	/identity
Method	OPTIONS
URL Params	none
Data Params	none
Success Response
Error Response	none