Record'in Rest JSON API Reference

The way of integration between Record'in and other software

This shows all Rest JSON API endpoints to integrate with Record'in software.


The same documentation in PDF format.





I. Purpose and intended audience

This document describes the Rest-JSON web services specifications of the Blockchain Record’in software.

It is intended to software engineers and developers willing to communicate with the Record’in software, either by scripting, or implementing a communication channel from another external software component like an ERP or a mobile application.



II. Blockchain objects JSON string description

All the objects are represented thanks to a JSON string representation inside the Blockchain.

Objects’ unique identifiers “UID” serve to recognize objects’ recordings being linked together in an historical timeline, sharing all the same “UID”.

IDs “ID” serve to recognize an individual historical snapshot of one object .

UIDs are formatted like following: “0035811b-0d4b-48fb-a359-5d70a523801b

IDs are composed of 3 sections:

<block number>.<transcation hash>.<object’s UID>

The JSON representation must follow a strict structure, and must also contain a set of metadata telling to the back-end node layer: the name of associated Java class to the object and the types of the attributes.

All the system attributes are managed by the backed node layer, and could not be overwritten. Only a subsection of them, inside the “attrMap” attribute is the placeholder for the “normal” attributes values, configured during the the objects’ models definitions.

<root>

├── [0] // the Java class fully qualified name string, including package name

└── [1] // json object containing the system attributes

   ├── uid // string object’s UID

   ├── id // string object’s ID

   ├── model // string object’s model name

   ├── index // string index name in which the object is stored

   ├── displayName // string name representation of the object

   ├── userOwnerID // json array containing the ID attribute of the object’s owner

   ├── userCreateID // json array containing the ID attribute of the object’s creator

   ├── userUpdateID // json array containing the ID attribute of the object’s modifier

   ├── userDeleteID // json array containing the ID attribute of the object’s deleter

   ├── dateTimeCreate // json array containing the time attribute of the object’s creation

   ├── dateTimeUpdate // json array containing the time attribute of the object’s modification

   ├── dateTimeDelete // json array containing the time attribute of the object’s deletion

   ├── nodeUpdateID // json array containing the string attribute of the node where the object was

   updated

   ├── modelID // json array containing the ID attribute of the object’s model

   ├── platformVersion // json array containing the platform version attribute served for building the

   this json representation

   ├── parentList // json array containing the list of IDs of the object’s historical snapshots

   ├── acl // json array containing a list of IDs to Acls objects

   ── attrMap // json array containing the Map of the “normal” attributes and values



We could find other attributes specific to Java classes like following for the “User”:

<root>

├── [0]

└── [1]

   ├── login // string login name of the user

   ├── address // Blockchain account address account

   ── attachment // json array containing pointer and metadata for the GDPR off-chain data storage



You can find a full example in Appendix 1: “Admin” user full JSON example.







III. WebServices endpoints

The full endpoints’ URL construction is the following (without parameters):

<http|https>://<recordin host>[:port]/<...>/<EndPoint>



<http|https> The HTTP protocol secure or not

< recordin host> The host where Record’in is listening from

[:port] Optional, the port number Record’in is listening from

<...> Corresponds to intermediate(s) path(s) name(s)

<EndPoint> Corresponds to the final part of the path name

1.Supported parameters methods

Record’in supports both “POST” and “GET” methods for sending parameter values.

In case of choosing the “POST” method, we recommend to use the following as sending (posting) content type HTTP header: “Content-Type: application/x-www-form-urlencoded”, for instance when using “postman” testing tool.

2.Authentication

Record’in webservices endpoints authenticate against Record’in directly. Once logged, the level of permission follows the one setup for that particular user inside the software, like if a person connects with that credentials within the web interface’s login page.



For login, there are 3 ways of passing the user credentials:

- HTTP Headers: Use of HTTP header “Authorization: BASIC <base 64 credentials>

- POST method: Use of “username” and “password” parameters

- GET method: Use of “username” and “password” parameters

Note that the “19.01” version of Record’in only supports HTTP Headers.



Be aware that if passing the user credentials (username and password) using the “GET” method, the authentication information will be visible inside the access log file “log/access.log”, and persisted during the log rotation period (15 days by default).



3.Returned results structure



All the requests or WebSocket messages returned from Record’in follow the same structure:

<root>

├── MessageType // Information about the message

└── MessageValue // The actual message content



Message types can be following :

- MenuUpdate: sends and updated structure of the menus to display

- Status: sends actual status informations about the Blockchain node

- Success: means the request has been executed without error

- SuccessBlock: means a record was succefgully mined inside a block

- Warning: contains a warning message

- WarningStay: contains a warning message, which will stay on screen

- Error: contains an error message

- ErrorStay: contains an error message, which will stay on screen





IV. Meta-model endpoints

1.JsonSchema



The ”JsonSchema” endpoint serves to retrieve informations about a model, like its attributes definitions as well as other kind of informations. See the response details for more information.



Endpoint :

/model/JsonSchema



Parameters:

- model: mandatory, the model name or the model ID:

Format example: “Menu

Format example: “17.c1f47 […] c640e8.42899 […] 15edd



Response details:

MessageValue

├── ModelSchema[1] // json array string representation of the model’s object

│   └── attrMap[1] // meta-model attributes list (serves for model objects update)

│      └── Attribute List[1] // model attributes list (serves for objects update)

├── JavaClasses // list of Java classes available (serves for model’s attributes update)

├── AttributeProperties // definition of the internal framework attributes meta model

├── ModelActionList // list of available actions for the model

├── Attributes // list of available attributes (serves for model’s attributes update)

├── Models // list of available Models (serves for model’s attributes update)

├── ModelID // ID of the model (serves for objects update)

└── ModelJavaClass // Java Class of the model (serves for objects update)





2.SearchMenu



The ”SearchMenu” endpoint serves to retrieve the hierarchical menu informations



Endpoint :

/model/SearchMenu



Parameters:

<None>



Response details:

MessageValue // list of menu entries





V. ORM endpoints

1.Action



The ”Action” endpoint serves to trigger an action on selected objects.



Endpoint action:

/orm/Action



Parameters:

- name: mandatory, the action’s name:

Format example: “Archive



- args: mandatory, the action’s arguments:

Format example: “{"ids":["f1474ed5-ccde-4c29-b881-6dbb48d4abff"]



Arguments nature and formats are linked to their actions. Some custom actions could require other values or data structure depending on the developers choices. Following actions are available on the platform by default:



- Archive: with a JSON object argument

This action serves to move objects to the “VIRTUAL_TABLES_ARCHIVED” index

<root>

└── ids // Json array containing a list of object UIDs to update



- UnArchive: with a JSON object argument

This action serves to move objects to the “VIRTUAL_TABLES_ACTIVE” index

<root>

└── ids // Json array containing a list of object UIDs to update



- Delete: with JSON a object argument

This action serves to move objects to the “VIRTUAL_TABLES_DELETED” index

<root>

└── ids // Json array containing a list of object UIDs to update

- ChangeOwner: with a JSON object argument

This action serves to change the objects’ owner

<root>

├── ids // Json array containing a list of object UIDs to update

└── args // Json array containing one object ID of a “User” object



- SetACL: with a JSON object argument

This action serves to update the objects’ ACLs

<root>

├── ids // Json array containing a list of object UIDs to update

└── args // Json array containing a list of ACL objects IDs



- CreatePrefrences: with a JSON object argument

This action serves to create a password for a user.

This action in only accessible form the “Admin>Preferences” menu.

<root>

├── ids // Json array empty

└── args // Json array string representation of a “CreatePreferences” transient object

   ├── [0] // the Java class “com.recordins.recordin.orm.BlockchainObject

   └── [1] // json object containing the system attributes

      ├── model // string object’s model name

      ├── modelID // json array containing the ID attribute of the object’s model

      ── attrMap // json array containing the object’s attributes and values

         ├── User // json array containing the ID attribute of the User” object

         ── Password // json array containing the Password attribute



You can find a “CreatePreference” example in Appendix 3: “CreatePreferences” object JSON example.



- RefreshPassword: with a JSON object argument

This action serves to update the local node users’ passwords in case they were not correctly reflected from the original node.

This action in only accessible form the “Admin>Preferences” menu.

<root>

└── ids // Json array containing a list of “User” objects UIDs to update



Response details:

MessageValue // string message



2.GetAttachment



The ”GetAttachment” endpoint serves to download a file attached to an object.



Endpoint action:

/orm/GetAttachment



Parameters:

- id: mandatory, the object’s ID:

Format example: “17.c1f47 […] c640e8.42899 […] 15edd



- attributeName: mandatory, the name of the object’s attribute

Format example: “User Manual



- nodeid: optional, the node ID requesting the attachment download. Serves for securing the data transfer between nodes.

Format example: “2123840ab0f05f85a [...] d23a9d

Default: “”



Response details:

<data of the requested attachment>



3.GetCurrentVersion



The ”GetCurrentVersion” endpoint serves to the current version of an object from an ID.



Endpoint action:

/orm/GetCurrentVersion



Parameters:

- id: mandatory, the object’s ID:

Format example: “17.c1f47 […] c640e8.42899 […] 15edd

Response details:

MessageValue // json array of the current object’s string representation



4.GetUserKeyAndCredentials



The ”GetUserKeyAndCredentials” endpoint serves to retrieve users’ account keys and credentials. It should be used by Blockchain nodes only, not clients.



Endpoint action:

/orm/GetUserKeyAndCredentials



Parameters:

- id: mandatory, the object’s ID:

Format example: “17.c1f47 […] c640e8.42899 […] 15edd



- nodeid: optional, the node ID requesting the attachment download. Serves for securing the credentials transfer between nodes.

Format example: “2123840ab0f05f85a [...] d23a9d

Default: “”



Response details:

<serialized AbstractMap.SimpleEntry(key, password)>



5.History



The ”History” endpoint serves to retrieve one object’s historical changes.



Endpoint action:

/orm/History



Parameters:

- id: mandatory, the object’s ID:

Format example: “17.c1f47 […] c640e8.42899 […] 15edd



Response details:

MessageValue // json array list of objects’ updates

├── [0] // json object of object’s update

│   ├── header // general information about the update

│   │    ├── date // timestamp of the update

│   │    ├── user // string representation of the user ID having made the update

│   │    └── create // boolean flag telling if it was the object creation

│   └── history // json array containing the details of changes on attributes values

│      ├── [0]

│      │    ├── op // string operation name

│      │    ├── path // string attribute name

│      │    └── value // json array containing the attribute string with the updated value

│      ├── [n+1] // next change to an attribute value

│      └── [n+2] // next change to an attribute value

├── [n+1] // next json object of object’s update

└── [n+2] // next json object of object’s update



6.Read



The ”Read” endpoint serves to read a set of records according to their IDs.



Endpoint action:

/orm/Read



Parameters:

- ids: mandatory, JSON array string of objects’ IDs:

Format example: “["17.c1f47 […] c640e8.42899 […] 15edd"]

Format example: “["17.c1f47 […] c640e8.42899 […] 15edd", "19.cf542 […] ab654d.128ac […] e3f45f"]



Response details:

MessageValue // list of JSON array returned read objects



7.ReadTree



The ”ReadTree” endpoint serves to read the relationships of a record with others and render in a tree structure.



Endpoint action:

/orm/ReadTree



Parameters:

- id: mandatory, the object’s ID:

Format example: “17.c1f47 […] c640e8.42899 […] 15edd



Response details:

MessageValue // json array list of objects’ updates

├── Model // string model name

├── Name // string object name

── children // json array of children

   ├── [0]

   │    ├Model // string model name

   │    ├Name // string object name

   │    └children // json array of children

   ├── [n+1]

   │    ├Model // string model name

   │    ├Name // string object name

   │    └children // json array of children

   └── [n+2]



8.Upload



The ”Uploadendpoint serves to send a document intended to be attached to a record’s attribute. This endpoint must be called using the “POST” http method only.



Endpoint action:

/orm/Upload



Parameters:

- fileName: mandatory, the name of the file to upload. This file name mus have following structure, the “unique identifier” could be a timestamp, and must have a length of 13 digits :

new_<unique identifier>_<real filename>

Format example: “new_1552839985118_document.pdf


The part containing the file content mus have following headers:

Content-Disposition: form-data; name="file"; filename="blob"

Content-Type: application/octet-stream


Response details:

None



9.Search



The ”Search” endpoint serves to lookup and read a set of records according to some criteria.



Endpoint action:

/orm/Search



Parameters:

- model: mandatory, the model name:

Format example: “Menu



- index: optional, the index name:

Format example: “archived

Default: “active



- oldVersion: optional, flag to ask for getting the old versions of the records

Format example: “<true|false>

Default: “false



- filter: optional, the filter to apply to the search endpoint in text or Json format

Format example: “user”, for looking inside all objects’ attributes values

Format example: “[["Name","=","user"]]”, for looking inside one attribute

Default: “”



- limit: optional, the maximum number of records to return

Format example: “20

Default: “-1”, “-1” means infinite



- offset: optional, the number of records to skip

Format example: “20

Default: “-1”, “-1” or “0” means none



- order: optional, the field name serving for sorting

Format example: “name

Format example: “name desc

Default: “”



Response details:

MessageValue

├── Count // number of returned objects

├── CountOld // number of old objects contained in counted results

└── BlockchainObjects // list of JSON array returned read objects



10.Write



The ”Write” enpoint serves to create or update an object.



Endpoint action:

/orm/Write


Parameters:

- model: mandatory, the model name:

Format example: “Menu



- vals: mandatory, the string representation of the object. The Platform will create a new object when no “parentList” property is present or empty.



Json minimal structure new object creation:

<root>

├── [0] // the Java class fully qualified name string, including package name

└── [1] // json object containing the system attributes

   ├── model // string object’s model name

   ├── modelID // json array containing the ID attribute of the object’s model

   ── attrMap // json array containing the Map of the “normal” attributes and values




You can find a full example in Appendix 2: Object creation JSON example.



For object update, it is recommanded to get the object’s full JSON first, by using “read” or “search” endpoints and to convert in a JSON object of your language to avoid manipulating data as string text.

Then just add/update/delete the relevant fields inside the “attrMap” attribute, and send the string representation of this updated JSON object into the “vals” parameter.



Json structure for object update (must contain a “parentList” property):

<root>

├── [0] // the Java class fully qualified name string, including package name

└── [1] // json object containing the system attributes

   ├── uid // string object’s UID

   ├── id // string object’s ID

   ├── model // string object’s model name

   ├── index // string index name in which the object is stored

   ├── displayName // string name representation of the object

   ├── userOwnerID // json array containing the ID attribute of the object’s owner

   ├── userCreateID // json array containing the ID attribute of the object’s creator

   ├── userUpdateID // json array containing the ID attribute of the object’s modifier

   ├── userDeleteID // json array containing the ID attribute of the object’s deleter

   ├── dateTimeCreate // json array containing the time attribute of the object’s creation

   ├── dateTimeUpdate // json array containing the time attribute of the object’s modification

   ├── dateTimeDelete // json array containing the time attribute of the object’s deletion

   ├── nodeUpdateID // json array containing the string attribute of the node where the object was

   updated

   ├── modelID // json array containing the ID attribute of the object’s model

   ├── platformVersion // json array containing the platform version attribute served for building the

   this json representation

   ├── parentList // json array containing the list of IDs of the object’s historical snapshots

   ├── acl // json array containing a list of IDs to Acls objects

   ── attrMap // json array containing the Map of the “normal” attributes and values



You can find a full example in Appendix 1: “Admin” user full JSON example.

Response details:

MessageValue // string message




VI. Status endpoint

1.GetNodeStatus



The ”GetNodeStatus” endpoint serves to retrieve node status informations and configuration items.



Endpoint :

/json/GetNodeStatus



Parameters:

<None>



Response details:

MessageValue

├── NodeID // string ID of the actual node

├── loggedUser // string name of the actual user requesting the node status informations

├── loggedUserID // string ID of the actual user requesting the node status informations

├── SyncComplete // flag telling the block synchronization with other nodes is complete

├── DatasetReady // flag telling the node’s data set is ready for mining

├── InitFlag / flag telling the node is initializing

├── Percent // integer percentage of achievement of syncing with other nodes or loading the dataset

├── SearchLimitMax // integer maximum number of returned objects

├── BlockLastImported // integer of the last block imported during syncing

├── BlockBestKnown // integer of the higher known block number

├── AttrID_REGEX_PATTERN // string regular expression pattern for validating IDs

├── IndexList // list of indexes containing their display name with their internal names

└── PrimitiveAttributes // list of attributes names with their corresponding root (mother) class name





VII. Appendix 1: “Admin” user full JSON example

[

"com.recordins.recordin.orm.User",

{

"userOwnerID": [

"com.recordins.recordin.orm.attribute.AttrID",

"1.init.init"

],

"userUpdateID": [

"com.recordins.recordin.orm.attribute.AttrID",

"1.48ac3846938c4a40f5769ac47db35ee6c97f982c584a99f1b3c84b1ffc4c3873.0035811b-0d4b-48fb-a359-5d70a523801b"

],

"dateTimeUpdate": [

"com.recordins.recordin.orm.attribute.AttrDateTime",

"12\\\/02\\\/2019 16:24:18"

],

"address": [

"com.recordins.recordin.orm.attribute.AttrString",

"95cdc0e564457b8d82e11fffc04a3b191cdd6429"

],

"modelID": [

"com.recordins.recordin.orm.attribute.AttrID",

"4.4f75ba2fef4dda444bab0c702d3211f95ca24d44626c542628522391ebc7085e.04b9e865-f61e-40e3-8f84-061a1e7335a9"

],

"displayName": "Admin",

"userDeleteID": null,

"index": "active",

"acl": [

"com.recordins.recordin.orm.attribute.AttrIDList",

[]

],

"dateTimeDelete": null,

"login": "admin",

"attrMap": [

"java.util.concurrent.ConcurrentSkipListMap",

{

"Address": [

"com.recordins.recordin.orm.attribute.AttrString",

"95cdc0e564457b8d82e11fffc04a3b191cdd6429"

],

"First Name": [

"com.recordins.recordin.orm.attribute.AttrString",

"Admin"

],

"Login": [

"com.recordins.recordin.orm.attribute.AttrString",

"admin"

],

"Last Name": [

"com.recordins.recordin.orm.attribute.AttrString",

""

],

"Name": [

"com.recordins.recordin.orm.attribute.AttrString",

"Admin"

]

}

],

"parentList": [

"com.recordins.recordin.orm.attribute.AttrIDList",

[

[

"AttrID",

"11.ef289e9ba3488661d6b9a03369ef4a90697169feab176f454340d130024f296c.0035811b-0d4b-48fb-a359-5d70a523801b"

],

[

"com.recordins.recordin.orm.attribute.AttrID",

"1.48ac3846938c4a40f5769ac47db35ee6c97f982c584a99f1b3c84b1ffc4c3873.0035811b-0d4b-48fb-a359-5d70a523801b"

]

]

],

"uid": "0035811b-0d4b-48fb-a359-5d70a523801b",

"attachment": [

"20190212-162418-attrMap.json",

"store-0\\\/0035811b-0d4b-48fb-a359-5d70a523801b\\\/20190212-162418-attrMap.json",

"aced0005737200286f72672e657468657265756d2e63727970746f2e45434b65792445434453415369676e61747572651bc5dbd022b6f038020003420001764c0001727400164c6a6176612f6d6174682f426967496e74656765723b4c00017371007e000178701c737200146a6176612e6d6174682e426967496e74656765728cfc9f1fa93bfb1d030006490008626974436f756e744900096269744c656e67746849001366697273744e6f6e7a65726f427974654e756d49000c6c6f776573745365744269744900067369676e756d5b00096d61676e69747564657400025b42787200106a6176612e6c616e672e4e756d62657286ac951d0b94e08b0200007870fffffffffffffffffffffffefffffffe00000001757200025b42acf317f8060854e0020000787000000020f1857830a11a85d30ed43e2d325285698436cadfaf8aae3efeae5d6eea5480eb787371007e0003fffffffffffffffffffffffefffffffe000000017571007e00070000002035c89b467776c4e5184363ed5b35150e4388fcfb3411840ab02fab1348289c8678",

"1.48ac3846938c4a40f5769ac47db35ee6c97f982c584a99f1b3c84b1ffc4c3873.0035811b-0d4b-48fb-a359-5d70a523801b",

"db9bb307bd5061c7459acbaf173563d894319b3ca6e360be1711932f203e7e81d7966dc18cbb1a0eb6527f875a5695c0a68f674327c3a8e56c66979ed0f4c01b"

],

"platformVersion": [

"com.recordins.recordin.orm.attribute.AttrPlatformVersion",

"1.0"

],

"nodeUpdateID": [

"com.recordins.recordin.orm.attribute.AttrString",

"db9bb307bd5061c7459acbaf173563d894319b3ca6e360be1711932f203e7e81d7966dc18cbb1a0eb6527f875a5695c0a68f674327c3a8e56c66979ed0f4c01b"

],

"userCreateID": [

"com.recordins.recordin.orm.attribute.AttrID",

"1.init.init"

],

"model": "User",

"dateTimeCreate": [

"com.recordins.recordin.orm.attribute.AttrDateTime",

"12\\\/02\\\/2019 16:13:07"

],

"id": "11.ef289e9ba3488661d6b9a03369ef4a90697169feab176f454340d130024f296c.0035811b-0d4b-48fb-a359-5d70a523801b"

}

]



VIII. Appendix 2: Object creation JSON example

["com.recordins.recordin.orm.Menu",

{

"attrMap":["java.util.concurrent.ConcurrentSkipListMap",

{

"Name":[

"com.recordins.recordin.orm.attribute.AttrString",

"Exemple"

],

"Model":[

"com.recordins.recordin.orm.attribute.AttrID",

"17.c1f47c3ca2b9f88b45c690591735d380e9dfed74f71456eeecb41d3c72c640e8.42899b3f-81d0-427d-92af-15339d415edd"

],

[… next attributes ... ]

}

],

"model":"Menu",

"modelID":[

"com.recordins.recordin.orm.attribute.AttrID",

"17.c1f47c3ca2b9f88b45c690591735d380e9dfed74f71456eeecb41d3c72c640e8.42899b3f-81d0-427d-92af-15339d415edd"

]

}

]





IX. Appendix 3: “CreatePreferences” object JSON example

[

"com.recordins.recordin.orm.BlockchainObject",

{

"attrMap": [

"java.util.concurrent.ConcurrentSkipListMap",

{

"User": [

"com.recordins.recordin.orm.attribute.AttrID",

"188.fc83188ff40aba0034d4f4e5540c491a7b2f24d85d72d7d06bf4a5c19cc4e3c2.968a0d7c-089b-45d7-86a9-b99a3044e8ff"

],

"Password": [

"com.recordins.recordin.orm.attribute.AttrPassword",

"password"

]

}

],

"model": "CreatePreferences",

"modelID": [

"com.recordins.recordin.orm.attribute.AttrID",

"17.f992af76d2ea91c1183cde495e4236af9cc1336933e8d5f259b0d362a78a3ef1.0c0815a2-12a3-474d-83ba-760cef8a96e3"

]

}

]