Chino.io API Docs
Chino.io API is built by developers for developers to simplify their life. It is based on RESTful principles and aims at providing great user experience.
If you notice anything that is against our objectives, please tell it to us at info@chino.io.
Managed Resources
Chino.io REST API provides access to a Document Oriented database (e.g. MongoDB) and borrows the main concepts of Documents and Schemas.
The following are the main resources:
-
Repository
is used to organize data and contains different Schema, Documents and BLOBs. -
Schema
describes the content (i.e. fields) of a Document. Is used to index securely documents and to allow search operations, leaving Documents encrypted. -
Document
contains the actual data in JSON format. Each Document is associated with a Schema. Document fields can contain also other representations (e.g. XML, HL7 or binary data). -
BLOB
is used to store large files through a chunk-based upload. To facilitate BLOB retrieval, each BLOB must have a corresponding Document containing metadata about it. -
Collection
is a grouping of documents. A collection can store documents of different types, so with different schema associated. It is used to have an easy to access sets of documents, e.g., all documents of a specific user. -
UserSchema
similarly toSchema
but a UserSchema describes the content (i.e. fields) of a User. -
User
is a person associated with a specific Chino.io customer who can store and access resources (based on the access rights). -
Group
is a group of users having the same access rights on a resource.
The API
For each resource Chino.io offers a series of RESTful operations that implement the CRUD (Create, Read, Update, Delete) paradigm.
Note
-
URL for Production APIs is
https://api.chino.io/v1
-
URL for SandBox API is
https://api.test.chino.io/v1
The SDKs
We have implemented SDK and wrappers for Python, Java, and C#. You can find the libraries on our github page.
You can also download and use the collection for postman.
To do so, create an environment with the variables {{customerId}}
and {{customerKey}}
set as your value.
Visit the console (Sandbox Console, Production Console) to automatically generate the environment.
Supported HTTPS requests:
The RESTful operations over defined resources support the following HTTP methods:
-
GET
- Retrieves a resource or list of resources -
POST
- Creates a resource -
PUT
- Updates a resource -
PATCH
- Partial Updates a resource (not available for all the resources) -
DELETE
- Delete a resource
Supported Server Responses
Responses leverage the following subset of standard HTTP status codes:
-
200 - OK
, the request was successful. -
204 - No Content
, the request was successful, the response is empty. -
400 - Bad Request
, the request could not be understood or was missing required parameters. -
401 - Unauthorized
, authentication failed, please login correctly. -
403 - Forbidden
, access denied to the requested resource due to the lack of privileges. -
404 - Not Found
, resource was not found. -
500 - Internal Server Error
, something wrong happened on the server. Please try again later and (possibly) report the accident to us. -
503 - Service Unavailable
, the service is temporarily unavailable. Try again later.
Requests
Request calls are accepted only over https. Calls on http protocol are forwarded to HTTPS be aware that the forward may lose the data, so don’t use the HTTP protocol. Chino.io uses URL encoding for GET
and DELETE
operations, and application/json
for POST
and PUT
operations.
Example: GET call with curl
An example of a GET
User operation:
(substitute the <Customer-Id>
and <Customer-Key>
with your values)
$ curl -X GET -u <Customer-Id>:<Customer-Key> https://api.chino.io/v1/users/<User-Id>
Example: POST call with curl
$ curl -X POST -u <Customer-Id>:<Customer-Key> -d '{
"username": "john",
"password": "password",
"is_active": true,
"attributes": {
"first_name": "John",
"last_name": "Doe",
"email": "john@acme.com"
}
}' https://api.chino.io/v1/user_schemas/77de01d8-492d-4cc2-a2b2-d3e76edc0657/users
Responses
All the Chino.io responses have application/json
as content-type
and the data are encapsulated in an object with meta-data.
The object that is returned has always the following fields:
-
result
: it’s a string that explains the result of the call, it can have two valuessuccess
orerror
-
result_code
: the HTTP code of the response -
message
: if the result is error this field contains the error message, otherwise it’s null. -
data
: if the result is success this field contains the content of the response, otherwise it’s null
The result_code
can be also accessed by the http_headers
of the call.
Note
For convenience, in this documentation we wrote only the correct (2XX
) responses. However, all the calls may return the error responses such as 404
, 500
etc.
Response example
A response message looks like this:
{
"result":"success",
"result_code": 200,
"messages": null,
"data": {}
}
Error response example
Error messages leverage the standard HTTP status codes and in addition provide the message
field which gives a better understanding of what went wrong.
{
"result":"error",
"result_code": 404,
"messages": "Not Found",
"data": null
}
Delete
Delete operations on Resources generally expect a force
attribute in the GET
parameters. When force
is set to False
, or force
is not present, the resource becomes inactive and it’s NOT deleted. To delete a Resource force must be set to True
.
For resources that contain data, such as Repository
or Schema
the delete operation is allowed only when the resource is empty. However, to simplify the work we offer the all_content
flag if it’s set to True
the operation deletes the resource and all its children and content. To use this flag you must use it with the force
set to True
.
Note
If a Resource is deactivated, it can be re-activated by Updating the resource setting the parameter is_active
as True
.
Caution
Force deleted Resources cannot be restored.
Caution
Children of deleted resources are automatically deleted.
Ex: Deleting a Schema
will delete all the Documents
associated with it.
List
All the API calls that return a list of results, such as the List of Documents
return the result in a paginated fashion. The paginated result has two values, offset
and limit
, that tells the start and end point of the result list.
Such that, the first page of the result has offest=0
and limit=10
.
Caution
The default value of limit
is set to 10
, however we still support a maximum value of 100
.
Note
To query the second page, or further pages, post as GET
parameters (appended to the end of the URL after the ?
) the values of offset
and limit
as you like (e.g. ?offset=10
).
User Authentication ¶
Chino.io has two type of user:
-
Application Developer: the person who develops the application and has access as admin to all the Resources liked to the account.
-
Application User: the users that use the application developed by the Application Developer.
Based on the category of users you want to use there are two different methods for the authentication (both using Basic Auth
).
Note
Basic Auth requires that the string is base64
encoded. If you are using plain http calls, or a library that does not implement the Basic Auth
methods, remember to encode the header before sending it to the server.
Application Developers
App developers or admins can use their <Customer-id>
and <Customer-key>
pair within each API call to access with admin privileges each resource.
<Customer-Key>
has infinite lifespan and is managed (created and invalidated) from the user profile page.
For the authentication, the <Customer-id>
is the user and the <Customer-key>
the password of the basic auth system.
Caution
Store the credential (the key) in a safe place and do not share it with anyone. Do not use these credentials in client side scripts but only in server side code.
Application Users
Application users use their username and password to authenticate. We implement the OAuth2 standard for authenticating users. We support two types of authentication flow:
-
password
: In which the user supplies the username and password to the developer’s app web page and then the developer’s server calls the authentication service for authenticating the users. [ref]. Note: since you are the “Resource Owner” and also the developer of the “Client”, then this option is safe for your apps. -
authorization code
: In which the user is presented with the Chino.io web page for login and, once the grant is performed, an automatic redirect returns a code to the developer’s application that calls the authentication service to get the token out of the code. [ref]
Note
For both cases it’s required to create an application. Applications can be created via the console or via API calls. Each application has its own authentication flow (password/authorization_code).
For each application the developer has a application_id
and application_secret
that are used for authenticating the calls.
Note
The access_token
expires after 30 minutes. To get a new token without asking the user to retype their username and password use the refresh_token
before its expiration.
Client types
Since OAuth2 is implemented to be used form a safe device, namely web server, or from a less safe device, such as a mobile or client application, OAuth2 implements and allows to client_types
, that is, public
or confidential
to allow the client to use, or not, the client_secret
.
Caution
While the client_id
identifies the APP, the client_secret
is like a password. The client_secret
must be kept safe, thus do not store the client_secret
in clients that are not safe, such as mobile apps or client side application. Store it only on the server side
-
public
: this type is specific for mobile and client applications. When an app is created with thepublic
type it does not require to specify theclient_secret
in the requests -
confidential
: this type is for server side use of the Oauth where theclient_secret
can be kept in the code in a safe way.
Note
A confidential client is an application that is capable of keeping a client password confidential to the world. This client password is assigned to the client app by the authorization server. This password is used to identify the client to the authorization server, to avoid fraud. An example of a confidential client could be a web app, where no one but the administrator can get access to the server, and see the client password.
A public client is an application that is not capable of keeping a client password confidential. For instance, a mobile phone application or a desktop application that has the client password embedded inside it. Such an application could get cracked, and this could reveal the password. The same is true for a JavaScript application running in the users browser. The user could use a JavaScript debugger to look into the application, and see the client password.
Caution
public
application are less secure when authenticating (since client_secret
is not needed) than confidential
. The API implements a method to limit the requests that are sent by public
applications.
Password
This method can be used via the API.
-
Developer creates an application (which support
password
as method). -
Developer creates a page where user can put his username and password
-
User fills the form and click send
-
The page calls the
auth/token
using, in the body:grant_type=password
username=<username>
password=<password>
client_id=<application_id>
client_secret=<application_secret>
(not required if app ispublic
)
-
Chino.io returns and object with
access_token
andrefresh_token
to be used.
Authorization code
This method does not use the API for most of its flow.
-
Developer creates an application that supports
authorization_code
as method, specifying acallback url
that points to a page he developed and that is able to get thecode
. -
When user wants to login, the developer application redirects to the Chino.io Oauth url, which looks like
https://api.chino.io/v1/auth/authorize?response_type=code&client_id=<APP-ID>
. -
User performs the login via the browser.
-
As soon as the login is performed Chino.io redirects the browser to the
callback-url
appending in the url thecode
that has to be used to get (parsing the URL from the server) theaccess_token
andrefresh_token
-
The developer application calls
auth/token
(to get theaccess_token
andrefresh_token
. ) with:grant_type=authorization_code
code=<code>
redirect_uri=<redirect_url>
client_id=<application_id>
client_secret=<application_secret>
(not required if app ispublic
)scope="read write"
Users and access to the APIs
The permission system allows an Application Developer to grant to any Application User access to any of the API. For more information, check the Permission section.
Note
Following APIs are for User and not for Developer (the latter uses CustomerId:CustomerKey
pair to identify their calls).
Get Token ¶
Get TokenPOST/auth/token/
This method allows users to get a valid token. A valid token can be obtained from username and password, authorization code or refresh token.
Note
The content-type
must be multipart/form-data
Example URI
Password
Headers
Content-Type: multipart/form-data
Body
grant_type=password
username=<username>
password=<password>
client_id=<application_id>
client_secret=<application_secret> (not required if app is `public`)
Authorization code
Headers
Content-Type: application/form-data
Body
grant_type=authorization_code
code=<code>
redirect_uri=<redirect_url>
client_id=<application_id>
client_secret=<application_secret> (not required if app is `public`)
scope="read write"
Refresh token
Headers
Content-Type: application/form-data
Body
grant_type=refresh_token,
refresh_token=<refresh_token>,
client_id=<application_id>,
client_secret=<application_secret> (not required if app is `public`)
200
Headers
Content-Type: application/json
Body
{
"result": "success",
"result_code": 200,
"message": null,
"data": {
"access_token": "ans2fN08sliGpIOLMGg3fv4BpPhWRq",
"token_type": "Bearer",
"expires_in ": 36000,
"refresh_token": "vL0durAhdhNNYFI27F3zGGHXeNLwcO",
"scope": "read write"
}
}
Revoke Token ¶
Logout invalidating the Access-Token
.
Revoke TokenPOST/auth/revoke_token/
Example URI
Headers
Content-Type: application/form-data
Body
token=<bearer_token>
client_id=<application_id>
client_secret=<application_secret>
200
Headers
Content-Type: application/json
Body
{
"result": "success",
"result_code": 200,
"message": null,
"data": null
}
Get Info ¶
Get the current session info.
Get InfoGET/users/me
Example URI
Headers
Content-Type: application/json
Authorization: Bearer <Bearer-Token>
200
Headers
Content-Type: application/json
Body
{
"result": "success",
"result_code": 200,
"message": null,
"data": {
"user": {
"username": "jack",
"user_id": "0e600eb0-921d-4682-92bf-857874c6ce54",
"insert_date": "2015-02-23T10:52:20.371",
"groups": [],
"attributes": {
"first_name": "Jack",
"last_name": "Sheppard",
"email": "jack@chino.io"
},
"last_update": "2015-02-23T10:52:20.372",
"is_active": true
}
}
}
Applications ¶
Create and manage applications that are used for the authentication of users
Applications ¶
ListGET/auth/applications
Example URI
Headers
Content-Type: application/json
Authorization: Basic <Customer-Id>:<Customer-Key>
200
Headers
Content-Type: application/json
Body
{
"result": "success",
"result_code": 200,
"message": null,
"data": {
"count": 2,
"total_count": 2,
"limit": 100,
"offset": 0,
"applications": [
{
"app_id": "R8tb59KneMIgrvoO5fZpuDmpM2o7Vwioqz4hiN1h",
"app_name": "test1"
},
{
"app_id": "ddwqUSiaj219dsanAaSIdjsamaskda0aJSKLiwad",
"app_name": "test2"
}
]
}
}
CreatePOST/auth/applications
Create an application.
Note
grant_type
can be authorization-code
or password
.
Notice that password
mode do not use redirect_url
.
Note
client_type
can be either public
or confidential
.
Default value is confidential
. Learn more about Client Types.
Example URI
Headers
Content-Type: application/json
Authorization: Basic <Customer-Id>:<Customer-Key>
Body
{
"name": "Test",
"grant_type": "password",
"client_type": "confidential"
}
200
Headers
Content-Type: application/json
Body
{
"message": null,
"data": {
"application": {
"app_secret": "9qJbeD9Gb0zpdFXuB9oRmW1ET9PvzYy9vFsc01IuxjCnJ6Cb6IEcRoLO7t7LW46C6XZUGaaF8Yso4rP7zSoJhvoh40LoI1T5A94AiDWIIe0lUgY0XXbT7hFjhYk1Jkad",
"grant_type": "password",
"app_name": "Test",
"app_id": "lMcaHVNwqAuGulPIEj8voH3FQhMKPbj5GzShsxVL"
}
},
"result": "success",
"result_code": 200
}
Application object ¶
ReadGET/auth/applications/{application_id}
Example URI
- application_id
string
(required) Example: lMcaHVNwqAuGulPIEj8voH3FQhMKPbj5GzShsxVLString
id
of theApplication
.
Headers
Content-Type: application/json
Authorization: Basic <Customer-Id>:<Customer-Key>
200
Headers
Content-Type: application/json
Body
{
"message": null,
"data": {
"application": {
"app_secret": "9qJbeD9Gb0zpdFXuB9oRmW1ET9PvzYy9vFsc01IuxjCnJ6Cb6IEcRoLO7t7LW46C6XZUGaaF8Yso4rP7zSoJhvoh40LoI1T5A94AiDWIIe0lUgY0XXbT7hFjhYk1Jkad",
"grant_type": "password",
"app_name": "Test",
"redirect_url": "http://127.0.0.1/",
"app_id": "lMcaHVNwqAuGulPIEj8voH3FQhMKPbj5GzShsxVL"
}
},
"result": "success",
"result_code": 200
}
UpdatePUT/auth/applications/{application_id}
Example URI
- application_id
string
(required) Example: lMcaHVNwqAuGulPIEj8voH3FQhMKPbj5GzShsxVLString
id
of theApplication
.
Headers
Content-Type: application/json
Authorization: Basic <Customer-Id>:<Customer-Key>
Body
{
"name": "Test2",
"grant_type": "password",
"redirect_url": "http://127.0.0.1/"
}
200
Headers
Content-Type: application/json
Body
{
"message": null,
"data": {
"application": {
"app_secret": "9qJbeD9Gb0zpdFXuB9oRmW1ET9PvzYy9vFsc01IuxjCnJ6Cb6IEcRoLO7t7LW46C6XZUGaaF8Yso4rP7zSoJhvoh40LoI1T5A94AiDWIIe0lUgY0XXbT7hFjhYk1Jkad",
"grant_type": "password",
"app_name": "Test2",
"redirect_url": "http://127.0.0.1/",
"app_id": "lMcaHVNwqAuGulPIEj8voH3FQhMKPbj5GzShsxVL"
}
},
"result": "success",
"result_code": 200
}
DeleteDELETE/auth/applications/{application_id}
Example URI
- application_id
string
(required) Example: lMcaHVNwqAuGulPIEj8voH3FQhMKPbj5GzShsxVLString
id
of theApplication
.
Headers
Content-Type: application/json
Authorization: Basic <Customer-Id>:<Customer-Key>
200
Headers
Content-Type: application/json
Body
{
"result": "success",
"result_code": 200,
"data": null,
"message": null
}
User Schema ¶
UserSchema
specifies the structure of the User
, that is, the fields that the User
associate to the UserSchema
must have.
Groups can be associated with UserSchemas. If a UserSchema has groups associated then each User created within that UserSchema will be added to the Groups. To associate a Group to a Schema see the API in the Group section.
Indexed field and Encryption
To implement Search operation Chino.io applies tokenization techniques on indexed fields, which are saved in cleartext but are cryptographically separated and explicitly unlinked from records. With this approach, when you perform a search the matching documents are decrypted and forwarded to you via HTTPS in milliseconds. However, to limit theoretical risks of links among fields, we advise developers to index only those fields that are needed and to try to avoid indexing of too many information. Contact us for more info.
UserSchemas ¶
ListGET/user_schemas
List all the UserSchemas create for the account that is making the request.
Example URI
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
200
Headers
Content-Type: application/json
Body
{
"data": {
"count": 1,
"limit": 100,
"offset": 0,
"total_count": 1,
"user_schemas": [
{
"description": "Encountersa",
"groups": [],
"insert_date": "2016-02-05T15:31:42.321Z",
"is_active": true,
"last_update": "2016-02-05T15:31:42.321Z",
"structure": {
"fields": [
{
"name": "test_string",
"type": "string"
}
]
},
"user_schema_id": "c4021bd4-cf6a-4e81-bf3c-7dcb89fe84fb"
}
]
},
"message": null,
"result": "success",
"result_code": 200
}
CreatePOST/user_schemas
Creates a UserSchema. Define the fields
within the structure
attributes using the type
and name
.
Valid types are:
-
integer
- Integer numbers -
array[integer]
- An array of integer, e.g.[1,2,3,4]
-
float
- Float numbers -
array[float]
- An array of integer, e.g.[1.1,2.2,3.3,4.4]
-
string
- String limited to 255 chars. -
array[string]
- An array of integer, e.g.["hi","how","are","you"]
-
text
- String of no limited length. This field cannot be indexed. -
boolean
- True or False -
date
- date in the form ofYYYY-MM-DD
. -
time
- time in the form ofHH:MM:SS.mmmmmm
orHH:MM:SS
. -
datetime
- datatime in the form ofYYYY-MM-DDTHH:MM:SS.mmmmmm
orYYYY-MM-DDTHH:MM:SS
. -
base64
- Base64 encoded strings no other character accepted. Never indexed. -
json
- Placeholder for any valid JSON node or object. It can be used for documents containing JSONs with multi level structures. JSON fields can’t be indexed.
The expected fields are:
-
description: (string, required) - description of the Schema
-
structure: (object, required) - the wrapper of fields
- fields: (array[Field], optional) - the list of fields
where Field
is defined as:
-
name: (string, required) - name of the field
-
type: (string, required) - one of the allowed type
-
indexed: (boolean, optional) - default is
false
, if it istrue
the field is indexed.
Example URI
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
Body
{
"description": "Encountersa",
"structure": {
"fields": [
{
"type": "string",
"name": "test_string"
}
]
}
}
200
Headers
Content-Type: application/json
Body
{
"message": null,
"data": {
"user_schema": {
"user_schema_id": "c4021bd4-cf6a-4e81-bf3c-7dcb89fe84fb",
"description": "Encountersa",
"is_active": true,
"last_update": "2016-02-05T15:31:42.321Z",
"groups": [],
"structure": {
"fields": [
{
"type": "string",
"name": "test_string"
}
]
},
"insert_date": "2016-02-05T15:31:42.321Z"
}
},
"result": "success",
"result_code": 200
}
UserSchema object ¶
ReadGET/user_schemas/{user_schema_id}
Example URI
- user_schema_id
string
(required) Example: e87012ef-b6f7-405d-9863-d35b99543389String
id
of theUserSchema
.
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
200
Headers
Content-Type: application/json
Body
{
"message": null,
"data": {
"user_schema": {
"user_schema_id": "c4021bd4-cf6a-4e81-bf3c-7dcb89fe84fb",
"description": "Encountersasda",
"is_active": false,
"last_update": "2016-02-05T15:47:44.884Z",
"groups": [],
"structure": {
"fields": [
{
"type": "string",
"name": "test_string"
},
{
"type": "string",
"name": "test_string1"
}
]
},
"insert_date": "2016-02-05T15:31:42.321Z"
}
},
"result": "success",
"result_code": 200
}
UpdatePUT/user_schemas/{user_schema_id}
Updates a user schema.
-
If a field is set from
indexed=False
toindexed=True
the user schema and users are reindexed. -
If a new field is added, the new users have to contain the value for the new field, old users will have the filed automatically set to
null
. -
It’s not possible to remove fields or remove indexing on a field.
Example URI
- user_schema_id
string
(required) Example: e87012ef-b6f7-405d-9863-d35b99543389String
id
of theUserSchema
.
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
Body
{
"description": "Encountersasda",
"structure": {
"fields": [
{
"type": "string",
"name": "test_string"
},
{
"type": "string",
"name": "test_string1"
}
]
}
}
200
Headers
Content-Type: application/json
Body
{
"message": null,
"data": {
"user_schema": {
"user_schema_id": "c4021bd4-cf6a-4e81-bf3c-7dcb89fe84fb",
"description": "Encountersasda",
"is_active": true,
"last_update": "2016-02-05T15:40:10.209Z",
"groups": [],
"structure": {
"fields": [
{
"type": "string",
"name": "test_string"
},
{
"type": "string",
"name": "test_string1"
}
]
},
"insert_date": "2016-02-05T15:31:42.321Z"
}
},
"result": "success",
"result_code": 200
}
DeleteDELETE/user_schemas/{user_schema_id}{?force}
Example URI
- user_schema_id
string
(required) Example: e87012ef-b6f7-405d-9863-d35b99543389String
id
of theUserSchema
.- force
boolean
(optional) Example: trueTo force (
true
) the delete or to only deactivate (false
)
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
200
Headers
Content-Type: application/json
Body
{
"message": null,
"data": null,
"result": "success",
"result_code": 200
}
Users ¶
User API allows one to create, retrieve, update and delete a User
.
Note
Users are linked to a the account, not to a repository, thus they can be used in any repository that belongs to your account.
List ¶
ListGET/user_schemas/{user_schema_id}/users
List all users that are created for the account that is making the request.
Example URI
- user_schema_id
string
(required) Example: e87012ef-b6f7-405d-9863-d35b99543389String
id
of theUserSchema
.
Headers
Content-Type: application/json
Authorization: Token <Access-Token> | <Customer-Id>:<Customer-Key>
200
Headers
Content-Type: application/json
Body
{
"result": "success",
"result_code": 200,
"message": null,
"data": {
"count": 100,
"total_count": 122,
"limit": 100,
"offset": 0,
"users": [
{
"username": "kate",
"schema_id": "d208a457-d6ac-472a-aee9-5221441066c6",
"user_id": "d88084ef-b6f7-405d-9863-d35b99543389",
"insert_date": "2015-02-23T17:06:18.402",
"last_update": "2015-02-23T17:06:18.402",
"is_active": true,
"attributes": {
"first_name": "Kate",
"last_name": "Austen",
"email": "kate@email.com"
},
"groups": [
"d88084ef-b6f7-405d-9863-d35b99543389",
"1eb39c88-3ac8-4664-b897-849dd260c72b"
]
},
{
"username": "jack",
"schema_id": "d208a457-d6ac-472a-aee9-5221441066c6",
"user_id": "a96994ed-2587-41e7-bf55-d2cd56053171",
"insert_date": "2015-02-23T17:01:26.369",
"last_update": "2015-02-23T17:01:26.369",
"is_active": true,
"attributes": {
"first_name": "Jack",
"last_name": "Shephard",
"email": "jack@physicians.com"
},
"groups": [
"d88084ef-b6f7-405d-9863-d35b99543389",
"1eb39c88-3ac8-4664-b897-849dd260c72b"
]
}
...
]
}
}
CreatePOST/user_schemas/{user_schema_id}/users
Create User
API requires username
and password
and accepts any additional information within node attributes
. The attributes must match the definition of the fields specified in the UserSchema
.
Expected fields are:
-
username (string, required)
- Unique username. 128 chars or less. Only letters, digits and @.±_ are allowed. -
password (string, required)
- password for the login. -
attributes (object, required)
- attributes of the user. The content must match the UserSchema definition. It can be an empty dict{}
Note
There may be a delay between the user creation and the possibility to search for it (see search).
To overcome this you can specify in the URL this ?consistent=true
which will make the indexing synchronous with the post of the document. However, this operation has a cost and can make the post call to last for seconds before answering.
Use it only when it’s really needed.
Note
Fields can be set as empty by using the null
value.
Example URI
- user_schema_id
string
(required) Example: e87012ef-b6f7-405d-9863-d35b99543389String
id
of theUserSchema
.
Headers
Content-Type: application/json
Authorization: <Customer-Id>:<Customer-Key>
Body
{
"username": "testUsernames",
"password": "testPassword",
"attributes": {
"test_string": "test"
},
"is_active": true
}
200
Headers
Content-Type: application/json
Body
{
"message": null,
"data": {
"user": {
"username": "testUsernames",
"schema_id": "3e3da5d3-15fc-4226-bfe9-5b29fccb38fb",
"user_id": "4cc0b976-587a-4a05-8f9e-1e1ba9b99670",
"insert_date": "2016-02-05T16:05:01.002Z",
"groups": [],
"attributes": {
"test_string": "test"
},
"is_active": true,
"last_update": "2016-02-05T16:05:01.042Z"
}
},
"result": "success",
"result_code": 200
}
User object ¶
ReadGET/users/{user_id}
Example URI
- user_id
string
(required) Example: d88084ef-b6f7-405d-9863-d35b99543389String
id
of theUser
.
Headers
Content-Type: application/json
Authorization: <Customer-Id>:<Customer-Key>
200
Headers
Content-Type: application/json
Body
{
"result": "success",
"result_code": 200,
"message": null,
"data": {
"user": {
"username": "james",
"schema_id": "d208a457-d6ac-472a-aee9-5221441066c6",
"user_id": "d88084ef-b6f7-405d-9863-d35b99543389",
"insert_date": "2015-02-05T10:53:38.157",
"last_update": "2015-02-05T10:53:38.157",
"is_active": true,
"attributes": {
"first_name": "James",
"last_name": "Ford",
"email": "james@acme.com"
},
"groups": [
"d88084ef-b6f7-405d-9863-d35b99543389",
"1eb39c88-3ac8-4664-b897-849dd260c72b"
]
}
}
}
UpdatePUT/users/{user_id}
Example URI
- user_id
string
(required) Example: d88084ef-b6f7-405d-9863-d35b99543389String
id
of theUser
.
Headers
Content-Type: application/json
Authorization: Token <Access-Token> | <Customer-Id>:<Customer-Key>
Body
{
"username": "james",
"password": "jamesstrongerpsw",
"is_active": true,
"attributes": {
"first_name": "James",
"last_name": "Ford",
"email": "james@acme.com
}
}
200
Headers
Content-Type: application/json
Body
{
"result": "success",
"result_code": 200,
"message": null,
"data": {
"user": {
"username": "james",
"schema_id": "d208a457-d6ac-472a-aee9-5221441066c6",
"user_id": "d88084ef-b6f7-405d-9863-d35b99543389",
"insert_date": "2015-02-05T10:53:38.157",
"last_update": "2015-02-05T10:53:38.157",
"is_active": true,
"attributes": {
"first_name": "James",
"last_name": "Ford",
"email": "james@acme.com"
},
"groups": [
"d88084ef-b6f7-405d-9863-d35b99543389",
"1eb39c88-3ac8-4664-b897-849dd260c72b"
]
}
}
}
Partial UpdatePATCH/users/{user_id}
Updates can be done by specifying only some fields and not all.
Example URI
- user_id
string
(required) Example: d88084ef-b6f7-405d-9863-d35b99543389String
id
of theUser
.
Headers
Content-Type: application/json
Authorization: Token <Access-Token> | <Customer-Id>:<Customer-Key>
Body
{
"attributes": {
"email": "james.ford@acme.com
}
}
200
Headers
Content-Type: application/json
Body
{
"result": "success",
"result_code": 200,
"message": null,
"data": {
"user": {
"username": "james",
"schema_id": "d208a457-d6ac-472a-aee9-5221441066c6",
"user_id": "d88084ef-b6f7-405d-9863-d35b99543389",
"insert_date": "2015-02-05T10:53:38.157",
"last_update": "2015-02-05T11:10:28.475",
"is_active": true,
"attributes": {
"first_name": "James",
"last_name": "Ford",
"email": "james.ford@acme.com"
},
"groups": [
"d88084ef-b6f7-405d-9863-d35b99543389",
"1eb39c88-3ac8-4664-b897-849dd260c72b"
]
}
}
}
DeleteDELETE/users/{user_id}{?force}
Note
You can use ?consistent=true
also for the delete operation.
Example URI
- user_id
string
(required) Example: d88084ef-b6f7-405d-9863-d35b99543389String
id
of theUser
.- force
boolean
(optional) Example: trueTo force (
true
) the delete or to only deactivate (false
)
Headers
Content-Type: application/json
Authorization: <Customer-Id>:<Customer-Key>
200
Body
{
"result": "success",
"result_code": 200,
"data": null,
"message": null
}
Consent Management ¶
Consent API allows you to create, retrieve, update, delete a Consent
.
In addition, the API allows you to search and list all Consent
updates or to filter out the consents of a specific User
.
Note
In the Consent
object the User
are identified by user_id
that is not linked to User
of Chino.io API.
You can use any identifier as user_id
for example: the user_id
of a User
object, an email
or an id
of your database
Structure
A consent object is structured as follow
{
"user_id": "admin@chino.io",
"description": "a long textual description",
"data_controller": {
"company": "Acme",
"contact": "John Doe",
"address": "221B Baker St.",
"email": "info@acme.com",
"VAT": "IT03256920228",
"on_behalf": true
},
"consent_id": "0a63b938-c481-42aa-8da2-1db34f2d0dea",
"purposes": [
{
"authorized": true,
"purpose": "marketing",
"description": "mailing list"
}
],
"policy_url": "https://chino.io/legal/privacy-policy",
"policy_version": "v1.0",
"withdrawn_date": null,
"inserted_date": "2018-01-26T13:16:28.680Z",
"collection_mode": "webform"
}
When withdrawn_date
is set, it means that the current consent has been withdrawn or modified by the user. This can happen in two cases:
-
when there’s an update, thus a new consent is created and linked with the previous (see
/history
) -
when the user withdraws his consent (see
Delete
)
Consents ¶
ListGET/consents
Optionally in the url is possible to pass user_id
to filter for the specific user. ?user_id=<user_id>
Example URI
Headers
Content-Type: application/json
Authorization: Basic <Customer-Id>:<Customer-Key>
200
Headers
Content-Type: application/json
Body
{
"message": null,
"data": {
"count": 2,
"total_count": 2,
"consents": [
{
"user_id": "admin@chino.io",
"description": "a long textual description",
"data_controller": {
"company": "Acme",
"contact": "John Doe",
"address": "221B Baker St.",
"email": "info@acme.com",
"VAT": "IT03256920228",
"on_behalf": true
},
"consent_id": "0a63b938-c481-42aa-8da2-1db34f2d0dea",
"purposes": [
{
"authorized": true,
"purpose": "marketing",
"description": "mailing list"
}
],
"policy_url": "https://chino.io/legal/privacy-policy",
"policy_version": "v1.0",
"withdrawn_date": null,
"inserted_date": "2018-01-26T13:16:28.680Z",
"collection_mode": "webform"
}
],
"limit": 10,
"offset": 0
},
"result": "success",
"result_code": 200
}
CreatePOST/consents
The create operation expects the following parameter:
-
user_id
(string, required) - a user identifier, any string up to 128 chars -
description
(string, required) - a textual description of the consent -
policy_url
(string, required) - the URL of the privacy policy -
policy_version
(string, required) - the policy version, string up to 16 chars -
collection_mode
(string, required) - how the consent was collected, string up to 32 chars -
data_controller
(JSONObject, required) - the Json containing the data of the controlleron_behalf
(boolean, required) - If the consent was collected on behalf of a data controllercompany
(string, required) - The company name, max 256 charscontact
(string, required) - The contact information, max 256 charsaddress
(string, required) - The address, max 256 charemail
(string, required) - A valid EmailVAT
(string, optional) - The company VAT
-
purpose
(list, required) - The list of purposes (JSONObjects)purpose
(string, required) - The purposes for which the consent has been authorized or not. max 32 charsdescription
(string, required) - The description of the purposeauthorized
(boolean, required) - if the purpose is authorized or not
Example URI
Headers
Content-Type: application/json
Authorization: Basic <Customer-Id>:<Customer-Key>
Body
{
"user_id": "admin@chino.io",
"description": "a long textual description",
"policy_version": "v1.0",
"policy_url": "https://chino.io/legal/privacy-policy",
"collection_mode": "webform",
"data_controller": {
"company": "Acme",
"contact": "John Doe",
"address": "221B Baker St.",
"email": "info@acme.com",
"VAT": "IT03256920228",
"on_behalf": true
},
"purposes": [
{
"purpose": "marketing",
"description": "mailing list",
"authorized": true
}
]
}
200
Headers
Content-Type: application/json
Body
{
"message": null,
"data": {
"consent": {
"user_id": "admin@chino.io",
"description": "a long textual description",
"data_controller": {
"company": "Acme",
"contact": "John Doe",
"address": "221B Baker St.",
"email": "info@acme.com",
"VAT": "IT03256920228",
"on_behalf": true
},
"consent_id": "0a63b938-c481-42aa-8da2-1db34f2d0dea",
"purposes": [
{
"authorized": true,
"purpose": "marketing",
"description": "mailing list"
}
],
"policy_url": "https://chino.io/legal/privacy-policy",
"policy_version": "v1.0",
"withdrawn_date": null,
"inserted_date": "2018-01-26T13:16:28.680Z",
"collection_mode": "webform"
}
},
"result": "success",
"result_code": 200
}
Consent Object ¶
ReadGET/consent/{consent_id}
Example URI
- consent_id
string
(required) Example: d88084ef-b6f7-405d-9863-d35b99543389String
id
of theConsent
.
Headers
Content-Type: application/json
Authorization: Basic <Customer-Id>:<Customer-Key>
200
Headers
Content-Type: application/json
Body
{
"message": null,
"data": {
"consent": {
"user_id": "admin@chino.io",
"description": "a long textual description",
"data_controller": {
"company": "Acme",
"contact": "John Doe",
"address": "221B Baker St.",
"email": "info@acme.com",
"VAT": "IT03256920228",
"on_behalf": true
},
"consent_id": "0a63b938-c481-42aa-8da2-1db34f2d0dea",
"purposes": [
{
"authorized": true,
"purpose": "marketing",
"description": "mailing list"
}
],
"policy_url": "https://chino.io/legal/privacy-policy",
"policy_version": "v1.0",
"withdrawn_date": null,
"inserted_date": "2018-01-26T13:16:28.680Z",
"collection_mode": "webform"
}
},
"result": "success",
"result_code": 200
}
UpdatePUT/consent/{consent_id}
The update creates a new consent and invalidates the previous one. The consent_id
remains the same, and the previous consent is linked to the new one to provide a history of the changes.
Example URI
- consent_id
string
(required) Example: d88084ef-b6f7-405d-9863-d35b99543389String
id
of theConsent
.
Headers
Content-Type: application/json
Authorization: Basic <Customer-Id>:<Customer-Key>
Body
{
"user_id": "admin@chino.io",
"description": "a long textual description",
"policy_version": "v1.0",
"policy_url": "https://chino.io/legal/privacy-policy",
"collection_mode": "webform",
"data_controller": {
"company": "Acme",
"contact": "John Doe",
"address": "221B Baker St.",
"email": "info@acme.com",
"VAT": "IT03256920228",
"on_behalf": true
},
"purposes": [
{
"purpose": "health data",
"description": "Processing of age and sex",
"authorized": true
},
{
"purpose": "marketing",
"description": "mailing list",
"authorized": true
}
]
}
200
Headers
Content-Type: application/json
Body
{
"message": null,
"data": {
"consent": {
"user_id": "admin@chino.io",
"description": "a long textual description",
"data_controller": {
"company": "Acme",
"contact": "John Doe",
"address": "221B Baker St.",
"email": "info@acme.com",
"VAT": "IT03256920228",
"on_behalf": true
},
"consent_id": "0a63b938-c481-42aa-8da2-1db34f2d0dea",
"purposes": [
{
"authorized": true,
"purpose": "health data",
"description": "Processing of age and sex"
},
{
"authorized": true,
"purpose": "marketing",
"description": "mailing list"
}
],
"policy_url": "https://chino.io/legal/privacy-policy",
"policy_version": "v1.0",
"withdrawn_date": null,
"inserted_date": "2018-01-26T13:20:44.160Z",
"collection_mode": "webform"
}
},
"result": "success",
"result_code": 200
}
DeleteDELETE/consents/{consent_id}
Caution
Deleting a consent invalidate the consent but does not remove it.
A delete consent cannot be Updated
.
Example URI
- consent_id
string
(required) Example: d88084ef-b6f7-405d-9863-d35b99543389String
id
of theConsent
.
Headers
Content-Type: application/json
Authorization: Basic <Customer-Id>:<Customer-Key>
200
Headers
Content-Type: application/json
Body
{
"result": "success",
"result_code": 200,
"data": null,
"message": null
}
history ¶
GET/consents/{consent_id}/history
Gets the history of the consent.
Example URI
- consent_id
string
(required) Example: d88084ef-b6f7-405d-9863-d35b99543389String
id
of theConsent
.
Headers
Content-Type: application/json
Authorization: Basic <Customer-Id>:<Customer-Key>
200
Body
{
"message": null,
"data":
"count": 2,
"total_count": 2,
"consents":[
{
"user_id": "admin@chino.io",
"description": "a long textual description",
"data_controller": {
"company": "Acme",
"contact": "John Doe",
"address": "221B Baker St.",
"email": "info@acme.com",
"VAT": "IT03256920228",
"on_behalf": true
},
"consent_id": "0a63b938-c481-42aa-8da2-1db34f2d0dea",
"purposes": [
{
"description": "Processing of age and sex",
"authorized": true,
"purpose": "health data"
},
{
"description": "mailing list",
"authorized": true,
"purpose": "marketing"
}
],
"policy_url": "https://chino.io/legal/privacy-policy",
"policy_version": "v1.0",
"withdrawn_date": null,
"inserted_date": "2018-01-26T13:20:44.160Z",
"collection_mode": "webform"
},
{
"user_id": "admin@chino.io",
"description": "a long textual description",
"data_controller": {
"company": "Acme",
"contact": "John Doe",
"address": "221B Baker St.",
"email": "info@acme.com",
"VAT": "IT03256920228",
"on_behalf": true
},
"consent_id": "0a63b938-c481-42aa-8da2-1db34f2d0dea",
"purposes": [
{
"purpose": "marketing",
"description": "mailing list",
"authorized": true
}
],
"policy_url": "https://chino.io/legal/privacy-policy",
"policy_version": "v1.0",
"withdrawn_date": "2018-01-26T13:20:44.160Z",
"inserted_date": "2018-01-26T13:16:28.680Z",
"collection_mode": "webform"
}
],
"limit": 10,
"offset": 0
},
"result": "success",
"result_code": 200
}
Groups ¶
Chino.io API allows to create, retrieve, update, delete a Group
, and to add/remove Users to Groups.
Groups
are introduced to help you to manage Permissions
more easily. Note: you can’t define Permissions
on UserSchema
(e.g. define that all Users
belonging to a UserSchema
have rights to access to a Repository
).
Note
Groups are linked to a Developer account, thus they can be used in any repository that belongs to the Application Developer account.
Groups ¶
ListGET/groups
List of all the groups that were created by the application
Example URI
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
200
Headers
Content-Type: application/json
Body
{
"result": "success",
"result_code": 200,
"message": null,
"data": {
"count": 2,
"total_count": 2,
"limit": 100,
"offset": 0
"groups": [
{
"insert_date": "2015-03-13T17:26:27.666",
"is_active": true,
"last_update": "2015-03-13T17:26:27.666",
"group_name": "Physicians",
"attributes": null,
"group_id": "fdd4f233-d1cb-4c24-82f5-445512d499be"
},
{
"insert_date": "2015-03-13T17:26:23.212",
"is_active": true,
"last_update": "2015-03-13T17:26:25.604",
"group_name": "Doctors",
"attributes": null,
"group_id": "1eb39c88-3ac8-4664-b897-849dd260c72b"
}
]
}
}
CreatePOST/groups
Create Group
API requires a group_name
that has to be unique and accepts any additional information within the node attributes
, like for Users
.
Expected parameters are
-
group_name: (string, required) - Name of the group
-
attributes (object, optional) - Object containing attributes that are stored as additional information. There is no need to define the
Schema
(like forUsers
) because theGroup
attributes are not indexed.
Example URI
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
Body
{
"group_name": "Physicians",
"attributes": {
"hospital": "Main Hospital"
}
}
200
Headers
Content-Type: application/json
Body
{
"result": "success",
"result_code": 200,
"message": null,
"data": {
"group": {
"group_name": "Physicians",
"group_id": "b427a45a-8e31-44f7-a11f-5c3fe205e42f"
"insert_date": "2015-03-13T18:06:21.242",
"is_active": true,
"last_update": "2015-03-13T18:06:21.242",
"attributes": {
"hospital": "Main Hospital"
}
}
}
}
Group Object ¶
ReadGET/groups/{group_id}
Example URI
- group_id
string
(required) Example: d88084ef-b6f7-405d-9863-d35b99543389String
id
of the Group.
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
200
Headers
Content-Type: application/json
Body
{
"result": "success",
"result_code": 200,
"message": null,
"data": {
"group": {
"group_name": "Physicians",
"group_id": "77de01d8-492d-4cc2-a2b2-d3e76edc0657",
"insert_date": "2015-02-07T12:14:46.754",
"is_active": true,
"last_update": "2015-02-21T19:07:45.832",
"attributes": {
"hospital": "Main Hospital"
}
}
}
}
UpdatePUT/groups/{group_id}
Example URI
- group_id
string
(required) Example: d88084ef-b6f7-405d-9863-d35b99543389String
id
of the Group.
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
Body
{
"group_name": "PhysiciansXYZ",
"is_active": true,
"attributes": {
"role": "oncologist",
"hospital": "Main Hospital"
}
}
200
Headers
Content-Type: application/json
Body
{
"result": "success",
"result_code": 200,
"message": null,
"data": {
"group": {
"group_name": "PhysiciansXYZ",
"group_id": "b427a45a-8e31-44f7-a11f-5c3fe205e42f"
"insert_date": "2015-03-13T18:06:21.242",
"is_active": true,
"last_update": "2015-03-13T18:06:21.242",
"attributes": {
"role": "oncologist",
"hospital": "Main Hospital"
}
}
}
}
DeleteDELETE/groups/{group_id}{?force}
Example URI
- group_id
string
(required) Example: d88084ef-b6f7-405d-9863-d35b99543389String
id
of theGroup
.- force
boolean
(optional) Example: trueTo force (
true
) the delete or to only deactivate (false
)
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
200
Body
{
"result": "success",
"result_code": 200,
"message": null,
"data": null
}
User and Groups ¶
Manage Group memberships, to add or remove a User
, or UserSchema
, from a Group
.
Add membersPOST/groups/{group_id}/users/{user_id}
Adds members to the specified Group
. You can add either a single User
or all the User of a UserSchema
.
Example URI
- group_id
string
(required) Example: d88084ef-b6f7-405d-9863-d35b99543389String
id
of theGroup
.- user_id
string
(required) Example: d88084ef-b6f7-405d-9863-d35b99543389String
id
of theUser
orUserSchema
to add or remove.
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
200
Headers
Content-Type: application/json
Body
{
"result": "success",
"result_code": 200,
"message": null,
"data": null
}
Remove membersDELETE/groups/{group_id}/users/{user_id}
Adds members to the specified Group
. You can remove either a single User
or all the User of a UserSchema
you have
previously added with Add members.
Example URI
- group_id
string
(required) Example: d88084ef-b6f7-405d-9863-d35b99543389String
id
of theGroup
.- user_id
string
(required) Example: d88084ef-b6f7-405d-9863-d35b99543389String
id
of theUser
orUserSchema
to add or remove.
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
200
Headers
Content-Type: application/json
Body
{
"result": "success",
"result_code": 200,
"data": null,
"message": null
}
List UsersGET/groups/{group_id}/users
This call returns a list of all Users that have been added to the Group.
Example URI
- group_id
string
(required) Example: 76cca5b6-dd9f-4d3b-8249-b8b23ca90b1bString
id
of the Group.
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
200
Headers
Content-Type: application/json
Body
{
"result": "success",
"result_code": 200,
"data": {
"count": 1,
"total_count": 1,
"limit": 10,
"users": [
{
"username": "james",
"schema_id": "d208a457-d6ac-472a-aee9-5221441066c6",
"user_id": "d88084ef-b6f7-405d-9863-d35b99543389",
"insert_date": "2015-02-05T10:53:38.157",
"last_update": "2015-02-05T10:53:38.157",
"is_active": true,
"attributes": {
"first_name": "James",
"last_name": "Ford",
"email": "james@acme.com"
},
"groups": [
"76cca5b6-dd9f-4d3b-8249-b8b23ca90b1b",
"1eb39c88-3ac8-4664-b897-849dd260c72b"
]
}
],
"offset": 0
},
"message": null
}
Permissions ¶
Intro
Permission API allows an Application Developer or an Application User that has proper rights to grant to users or groups permissions over resources.
There are 7 types of permissions:
-
C
: Create - valid only for multiple resources (e.g. /documents) -
R
: Read - valid for all resources -
U
: Update - valid for all resources -
D
: Delete - valid for all resources -
L
: List - valid only for multiple resources (e.g. /documents) -
A
: Administer (see explanation later) -
S
: Search (valid only fordata
grants overSchema
)
A permission over a resource specifies what are the API calls that a user can perform over that resource. Permissions over a resource do not have impact on its children.
Examples:
-
a
C
permission onRepository
allows one to call thePOST
method to create a newRepository
. -
a
R
permission onRepository
allows one to call theGET
method to read the description ofRepositories
but not their content. Thus, the call returns theRepository
description and not the containedSchema
. -
a
R
permission onSchema
allows one to call theGET
method to read the specifiedSchema
. This call returns theSchema
description, fields, and id but not theDocuments
. To read theDocuments
the application developer has to grant the permission on the child Resource (Document
) of the specificSchema
. (see Permission resource children)
Permission format
The format (json) to specify a permission is the following:
{
"manage":[ "R", "U", "D" ],
"authorize":[ "R", "U", "D", "A" ]
}
The object has two fields, each of them is an array of grants:
-
manage
: specifies the grants that are given to the specified user. -
authorize
: specifies the grants that the specified user can assign to other users.
The authorize field provides a fine grain capability to decide what each user can grant to other users.
Note
Grants for a specific object (see Permission Resource), can have {"manage":["R","U","D"],"authorize":["R","U","D","A"]}
, while over the Resource children (Permission Resource Children) can have {"manage":["C","R","U","D","L"],"authorize":["C","R","U","D","L","A"]}
(with L and A)
The “A” for Administer
Chino.io has a non-common grant A
for Administer
. This is a special grant that gives to a user the possibility to administer the grants for other users. In other words, a user with this grant can transfer to a second user the ability to authorize a third user. Administer gives also the possibility to revoke grants for other users.
Note
A
can be used only in the authorize field.
Examples
Ex1
Alice
has: {"manage":["R", "U", "D"], "authorize":[ "R", "U", "D", "A"]}
Can grant any permission to Bob
: "manage":[ "R", "U", "D"], "authorize":[ "R", "U", "D", "A"]
Ex2
Alice
has: "manage":["R", "U", "D"]
Cannot grant any permission to Bob
.
Ex3
Alice
has: "manage":["R", "U", "D"], "authorize":[ "R", "U", "D"]
Can grant permission to Bob
: "manage":[ "R", "U", "D"]
Ex4
Alice
has: "manage":["R", "U", "D"], "authorize":[ "R", "U", "D", "A"]
Bob
has: "manage":["R", "U", "D"]
Alice
can revoke permission to Bob
Ex5
Alice
has: "manage":["R", "U", "D"], "authorize":[ "R", "U", "D"]
Bob
has: "manage":["R", "U", "D"]
Alice
cannot revoke permission to Bob
because it misses the A
permission that would have given to Alice
the possibility to revoke the authorization.
The “S” for Search
Another non-common grant is the S
to specify if a user can perform a Search
over the selected Resource
.
Since the search works only over Schema
or UserSchema
this value can be used for specifying grants over only to
those two.
Note
The S
Permission has different effects on Schemas and UserSchemas:
-
Schema
: the user will get in the Search results only the documents for which s/he has aR
grant -
UserSchema
: the user will receive in the results ALL the users, regardless of existing Permissions.
The permission is granted by adding the S
grant in the manage or authorize list.
Grants on Created Documents
When a new document is created within a Schema
, by default its creator has no access rights over it.
You can set default Permissions for Documents that are created in a Schema with the created_document
object,
which describes the default access rights that are applied to the desired subject.
In the example below, when Alice
creates a document she immediately gets RUD
over it and the possibility to
authorize RUDA
over that document, while she cannot see other Documents in the Schema:
{
"manage": ["C"],
"authorize": [],
"created_document": {
"manage":["R", "U", "D"],
"authorize":["R", "U", "D", "A"]
}
}
Note that, if the Permissions are specified outside the created_document
object, there is no need to add them inside!
In the previous example, if the external manage list contains R
, the Permission is granted on all the Schema’s
children, including the new Documents that Alice creates in the future; thus specifying R
in
created_document.manage would be redundant.
Note
The created_document
object is only available with this API call
when choosing schemas
as resource type. If used in another context, it will return an error.
The Calls
We have three calls:
-
Resources: this one specifies the grants for all the resources of that type. It’s for the basic types. Ex:
repository/
, which is to grant the user the possibility to manage all the repositories. -
Resource: this one specifies the grants for a specific resource identified with an
id
. Ex:schema/72131278123...
, which is a grant on the specifiedSchema
-
Resource children: this call specifies the grants for all the objects of the specified type that are contained in the resource identified with the
id
. Exschema/72131278123.../documents
, which is the grant on all the documents of the specifiedSchema
.
To grant or revoke a permission each URL starts with an action
parameter that specifies if it’s a grant
or revoke
operation.
The permission can be granted to either a specific User
or to a Group
of users. To do so we have subject_type
which is either User
or Group
and subject_id
which is either the id
of the User
or of the Group
.
Note
always use plural and lower case form of the resources in the URL. Ex: user_schemas
for defining permissions for UserSchema.
Resource Structure
To understand the Permissions system, we have built a table that explains the parent-child hierarchy of the resources:
Top level | 2nd level | 3rd level |
---|---|---|
Repository | Schema | Document |
UserSchema | User | |
Group | ||
Collection |
For example, Schemas are parents of Documents and children of Repositories.
Permission on Resources ¶
Permission on ResourcesPOST/perms/{action}/{resource_type}/{subject_type}/{subject_id}
This call specifies the permission over resources of a specific type.
It can be used only on Top Level resources:
resource type | manage | authorize |
---|---|---|
repositories | C R U D L |
C R U D L A |
user_schemas | C R U D L |
C R U D L A |
groups | C R U D L |
C R U D L A |
collections | C R U D L |
C R U D L A |
Example to grant to a group of users permission over all the Repositories.
-
resource_type
:repositories
-
subject_type
:groups
-
subject_id
:<group_id>
the ID of the Group we want to give the grant to
Example URI
- action
string
(required) Example: grantString can be
grant
orrevoke
.- resource_type
string
(required) Example: respositoriesString
name
of theResource
.- subject_type
string
(required) Example: usersString can be
users
orgroups
.- subject_id
string
(required) Example: e00084ef-b6f7-42131-9863-d35b99543389String
id
thesubject type
identifier.
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
Body
{
"manage": [
"C"
]
}
200
Headers
Content-Type: application/json
Body
{
"result": "success",
"result_code": 200,
"message": null,
"data": {}
}
Permissions on a Resource ¶
Permission on a ResourcePOST/perms/{action}/{resource_type}/{resource_id}/{subject_type}/{subject_id}
This call specifies the permission over a specific resource.
This call can be used on all resources:
resource type | manage | authorize |
---|---|---|
documents | R U D |
R U D A |
schemas | R U D |
R U D A |
repositories | R U D |
R U D A |
users | R U D |
R U D A |
user_schemas | R U D |
R U D A |
groups | R U D |
R U D A |
collections | R U D |
R U D A |
Example to grant to a group of users permission over a specific repository.
-
resource_type
:repositories
-
resource_id
:<repository_id>
-
subject_type
:groups
-
subject_id
:<group_id>
the ID of the Group we want to give the grant to
Example URI
- action
string
(required) Example: grantString can be
grant
orrevoke
.- resource_type
string
(required) Example: schemasString
name
of theResource
.- resource_id
string
(required) Example: d8sdf324ef-b6f7-405d-9863-d35b99543389String
id
of theResource
.- subject_type
string
(required) Example: usersString can be
users
orgroups
.- subject_id
string
(required) Example: e00084ef-b6f7-42131-9863-d35b99543389String
id
thesubject type
identifier.
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
Body
{
"manage": [
"R"
]
}
200
Headers
Content-Type: application/json
Body
{
"result": "success",
"result_code": 200,
"message": null,
"data": {}
}
Permission on Resource Children ¶
Permission on Resource ChildrenPOST/perms/{action}/{resource_type}/{resource_id}/{resource_child_type}/{subject_type}/{subject_id}
This call specifies the permission over all the children of a specific resource.
This call can be used only on resources that have a parent-child relationship (see the resources table):
Example to grant to a group of users permission over all the schemas of a specific repository.
-
resource_type
:repositories
-
resource_id
:<repository_id>
-
resource_child_type
:schemas
-
subject_type
:groups
-
subject_id
:<group_id>
Example URI
- action
string
(required) Example: grantString can be
grant
orrevoke
.- resource_type
string
(required) Example: repositoriesString
name
of theResource
that his parent of theresource type
.- resource_id
string
(required) Example: d8sdf324ef-b6f7-405d-9863-d35b99543389String
id
of theParent
.- resource_child_type
string
(required) Example: schemasString
name
of theResource
on which grants are applied- subject_type
string
(required) Example: groupsString can be
users
orgroups
.- subject_id
string
(required) Example: e00084ef-b6f7-42131-9863-d35b99543389String
id
thesubject type
identifier.
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
Body
{
"manage": [
"C"
]
}
200
Headers
Content-Type: application/json
Body
{
"result": "success",
"result_code": 200,
"message": null,
"data": {}
}
Read Permissions on all Resources ¶
Read Permissions on all ResourcesGET/perms
List all the permissions that the current user making the request has on all the Resources.
(It works only for the users you have created, we don’t list all your permissions as users that logs in with <Customer-Id>:<Customer-Key>
)
Note
This call does not show permission over Documents. Document permission may generate a way too long list, so we skip it.
Example URI
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
200
Headers
Content-Type: application/json
Body
{
"message": null,
"data": {
"permissions": [
{
"access": "Structure",
"parent_id": null,
"resource_type": "Repository",
"owner_id": "11308a6-229d-7100-x230-562324677710",
"owner_type": "users",
"permission": {
"Manage": [
"R"
]
}
},
{
"access": "Data",
"resource_id": "719081b6-429d-4700-a690-661814972730",
"resource_type": "Schema",
"owner_id": "11308a6-229d-7100-x230-562324677710",
"owner_type": "users",
"permission": {
"Authorize": [
"A"
],
"Manage": [
"R",
"U",
"L"
]
}
}
]
},
"result": "success",
"result_code": 200
}
Read Permissions on a Document ¶
Read Permissions on a DocumentGET/perms/documents/{document_id}
List all the permissions over a Document.
Note
In this call, the list of permission have resource_id
and resource_type
set as the owner of the permission. This can either be a User
or a Group
Note
Application Developer can make this call. Application User must have R
on the Document
Example URI
- document_id
string
(required) Example: c469d583-1e81-424e-b1ca-70822706dc5fid
of theDocument
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
200
Headers
Content-Type: application/json
Body
{
"message": null,
"data": {
"permissions": [
{
"access": "Data",
"resource_id": "55f8b0e3-d1f1-4644-9d4d-672c5b362b26",
"resource_type": "User",
"permission": {
"Manage": [
"R",
"U"
]
}
}
]
},
"result": "success",
"result_code": 200
}
Read Permissions of a User ¶
Read Permissions of a UserGET/perms/users/{user_id}
List all the permissions that the user specified via the id has on Resources.
Note
Application Developer can make this call. Application User can only make the call specifying their own id.
Note
This call does not show permission over Documents. Document permission may generate a way too long list, so we skip it.
Example URI
- user_id
string
(required) Example: 119083b6-19d-1000-a100-426114272730id
of theUser
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
200
Headers
Content-Type: application/json
Body
{
"message": null,
"data": {
"permissions": [
{
"access": "Structure",
"parent_id": null,
"resource_type": "Repository",
"owner_id": "119083b6-19d-1000-a100-426114272730",
"owner_type": "users",
"permission": {
"Manage": [
"R",
"U"
]
}
}
]
},
"result": "success",
"result_code": 200
}
Read Permissions of a Group ¶
Read Permissions of a GroupGET/perms/groups/{group_id}
List all the permissions that the group specified via the id has on Resources.
Note
Application Developer can make this call. Application User can only make the call specifying an id of a Group they belong to.
Note
This call does not show permission over Documents. Document permission may generate a way too long list, so we skip it.
Example URI
- group_id
string
(required) Example: 3322383b6-19d-1800-a100-516113322730id
of theGroup
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
200
Headers
Content-Type: application/json
Body
{
"message": null,
"data": {
"permissions": [
{
"access": "Structure",
"parent_id": null,
"resource_type": "Repository",
"owner_id": "3322383b6-19d-1800-a100-516113322730",
"owner_type": "groups",
"permission": {
"Manage": [
"R",
"U"
]
}
}
]
},
"result": "success",
"result_code": 200
}
Repositories ¶
User API allows one to create, retrieve, update, delete a Group
.
Note
Repositories are linked to a Developer account, thus they can be used in any repository that belongs to the Application Developer account.
Repositories ¶
ListGET/repositories
Example URI
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
200
Headers
Content-Type: application/json
Body
{
"result": "success",
"result_code": 200,
"message": null,
"data": {
"count": 10,
"total_count": 10,
"limit": 100,
"offset": 0,
"repositories": [
{
"repository_id": "670a3a91-575f-4e34-b8a4-62ef74ce0764",
"last_update": "2015-02-24T09:24:20.139",
"is_active": false,
"description": "Encounters",
"insert_date": "2015-02-24T09:24:20.139"
},
{
"repository_id": "b101995d-c06c-4b90-a862-5eb11b72feb3",
"last_update": "2015-02-21T17:24:14.496",
"is_active": true,
"description": "Patient documents",
"insert_date": "2015-02-21T17:24:14.495"
}
]
}
}
CreatePOST/repositories
The create operation expects the following parameter:
description
(string, required) - the description of the Repository
Example URI
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
Body
{
"description": "This is a test repo"
}
200
Headers
Content-Type: application/json
Body
{
"result": "success",
"result_code": 200,
"message": null,
"data": {
"repository": {
"repository_id": "d88084ef-b6f7-405d-9863-d35b99543389",
"last_update": "2015-02-24T21:48:16.332",
"is_active": true,
"description": "This is a test repo",
"insert_date": "2015-02-24T21:48:16.332"
}
}
}
Repository Object ¶
ReadGET/repositories/{repository_id}
Example URI
- repository_id
string
(required) Example: d88084ef-b6f7-405d-9863-d35b99543389String
id
of theRepository
.
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
200
Headers
Content-Type: application/json
Body
{
"result": "success",
"result_code": 200,
"message": null,
"data": {
"repository": {
"repository_id": "d88084ef-b6f7-405d-9863-d35b99543389",
"last_update": "2015-02-24T21:48:16.332",
"is_active": true,
"description": "This is a test repo",
"insert_date": "2015-02-24T21:48:16.332"
}
}
}
UpdatePUT/repositories/{repository_id}
Example URI
- repository_id
string
(required) Example: d88084ef-b6f7-405d-9863-d35b99543389String
id
of theRepository
.
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
Body
{
"description": "Stores old docs produced by physicians (not used anymore)",
"is_active": false
}
200
Headers
Content-Type: application/json
Body
{
"result": "success",
"result_code": 200,
"message": null,
"data": {
"repository": {
"repository_id": "d88084ef-b6f7-405d-9863-d35b99543389",
"last_update": "2015-02-24T21:48:16.332",
"is_active": false,
"description": "Stores old docs produced by physicians (not used anymore)",
"insert_date": "2015-02-24T21:48:16.332"
}
}
}
DeleteDELETE/repositories/{repository_id}{?force}
Caution
Deleting a Repository
will delete all the Schemas
and Documents
stored within it.
A deleted Repository
cannot be restored
Example URI
- repository_id
string
(required) Example: d88084ef-b6f7-405d-9863-d35b99543389String
id
of theRepository
.- force
boolean
(optional) Example: trueTo force (
true
) the delete or to only deactivate (false
)
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
200
Headers
Content-Type: application/json
Body
{
"result": "success",
"result_code": 200,
"data": null,
"message": null
}
Schemas ¶
Indexed field and Encryption
To implement Search operation Chino.io applies tokenization techniques on indexed fields, which are saved in cleartext but are cryptographically separated and explicitly unlinked from records. With this approach, when you perform a search the matching documents are decrypted and forwarded to you via HTTPS in milliseconds. However, to limit theoretical risks of links among fields, we advise developers to index only those fields that are needed and to try to avoid indexing of too many information. Contact us for more info.
Schemas ¶
Schemas define the structure of Documents
. The following are the types of data fields that are supported:
-
integer
- Integer numbers -
array[integer]
- An array of integer, e.g.[1,2,3,4]
-
float
- Float numbers -
array[float]
- An array of integer, e.g.[1.1,2.2,3.3,4.4]
-
string
- String limited to 255 chars. -
array[string]
- An array of integer, e.g.["hi","how","are","you"]
-
text
- String of no limited length. This field cannot be indexed. -
boolean
- True or False -
date
- date in the form ofYYYY-MM-DD
. -
time
- time in the form ofHH:MM:SS.mmmmmm
orHH:MM:SS
. -
datetime
- datetime in the form ofYYYY-MM-DDTHH:MM:SS.mmmmmm
orYYYY-MM-DDTHH:MM:SS
. -
base64
- Base64 encoded strings no other character accepted. Never indexed. -
json
- Placeholder for any valid JSON node or object. It can be used for documents containing JSONs with multi-level structures. JSON fields can’t be indexed. -
blob
- Placeholder for Blob uploads. See Blob section for more details.
Note
The fields accept empty value as null
.
Note
Each schema field can be indexed to enable fast search operations over it. To index a schema field put "indexed": true
within the fields definition.
For array
the condition in the search is satisfied when at least one element satisfies the condition.
ListGET/repositories/{repository_id}/schemas
The list of schemas within the specified Repository
Example URI
- repository_id
string
(required) Example: d88084ef-b6f7-405d-9863-d35b99543389String
id
of theRepository
on which the user wants to get the schemas.
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
200
Headers
Content-Type: application/json
Body
{
"result": "success",
"result_code": 200,
"message": null,
"data": {
"count": 2,
"total_count": 2,
"limit": 100,
"offset": 0,
"schemas": [
{
"description": "TestFields",
"schema_id": "b1cc4a53-19a1-4819-a8c7-20bf153ec9cf",
"repository_id": "3ddba8af-6965-4416-9c5c-acf6af95539d",
"is_active": true,
"insert_date": "2015-02-15T16:22:04.058"
"last_update": "2015-02-15T16:22:04.058",
"structure": {
"fields": [
{
"type": "integer",
"name": "test_int",
"indexed":true
},
{
"type": "float",
"name": "test_float",
"indexed":true
},
{
"type": "string",
"name": "test_string",
"indexed":true
},
{
"type": "boolean",
"name": "test_boolean",
"indexed":true
},
{
"type": "date",
"name": "test_date"
},
{
"type": "time",
"name": "test_time"
},
{
"type": "datetime",
"name": "test_datetime"
}
]
}
},
{
"description": "Encounters",
"schema_id": "628dbb1b-3839-413b-91c9-0dc375d3b332",
"repository_id": "48311494-1d60-4e97-889f-11e90b381efa",
"is_active": true,
"insert_date": "2015-02-19T16:39:47.282",
"last_update": "2015-02-20T11:18:24.913",
"structure": {
"fields": [
{
"type": "string",
"name": "physician_id",
"indexed":true
},
{
"type": "string",
"name": "physician_name",
"indexed":true
},
{
"type": "string",
"name": "observation"
},
{
"type": "datetime",
"name": "visit_date",
"indexed":true
}
]
}
}
]
}
}
CreatePOST/repositories/{repository_id}/schemas
Create a new Schema
. A Schema
describes Documents
content and it consists of an array of objects of pairs field-name
and field-type
.
The expected fields are:
-
description: (string, required)
- description of the Schema -
structure: (object, required)
- the wrapper of fieldsfields: (list[Field], required)
- the list of fields
where Field
is defined as:
-
name: (string, required)
- name of the field -
type: (string, required)
- one of the allowed type -
indexed (boolean, optional)
- if the field has to be indexed
Example URI
- repository_id
string
(required) Example: d88084ef-b6f7-405d-9863-d35b99543389String
id
of theRepository
on which the user wants to get the schemas.
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
Body
{
"description": "testSchema",
"structure": {
"fields": [
{
"name": "physician_id",
"type": "string",
"indexed": true
},
{
"name": "patient_birth_date",
"type": "date",
"indexed": true
},
{
"name": "observation",
"type": "string"
},
{
"name": "visit_date",
"type": "datetime",
"indexed": true
}
]
}
}
200
Headers
Content-Type: application/json
Body
{
"result": "success",
"result_code": 200,
"message": null,
"data": {
"schema": {
"repository_id": "48311494-1d60-4e97-889f-11e90b381efa",
"description": "testSchema",
"is_active": false,
"insert_date": "2015-02-24T22:56:00.763",
"last_update": "2015-02-24T22:56:00.763",
"schema_id": "6ef67cf5-02e3-4f77-8cc7-b632b233baee",
"structure": {
"fields": [
{
"name": "physician_id",
"type": "string",
"indexed": true
},
{
"name": "patient_birth_date",
"type": "date",
"indexed": true
},
{
"name": "observation",
"type": "string"
},
{
"name": "visit_date",
"type": "datetime",
"indexed": true
}
]
}
}
}
}
Schema Object ¶
ReadGET/schemas/{schema_id}
Example URI
- schema_id
string
(required) Example: d88084ef-b6f7-405d-9863-d35b99543389String
id
of theSchema
.
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
200
Headers
Content-Type: application/json
Body
{
"result": "success",
"result_code": 200,
"message": null,
"data": {
"schema": {
"description": "testSchema",
"schema_id": "b1cc4a53-19a1-4819-a8c7-20bf153ec9cf",
"repository_id": "3ddba8af-6965-4416-9c5c-acf6af95539d",
"is_active": true,
"insert_date": "2015-02-15T16:22:04.058",
"last_update": "2015-02-15T16:22:04.058",
"structure": {
"fields": [
{
"type": "integer",
"name": "test_int",
"indexed": true
},
{
"type": "float",
"name": "test_float",
"indexed": true
},
{
"type": "string",
"name": "test_string",
"indexed": true
},
{
"type": "boolean",
"name": "test_boolean",
"indexed": true
},
{
"type": "date",
"name": "test_date"
},
{
"type": "time",
"name": "test_time"
},
{
"type": "datetime",
"name": "test_datetime"
}
]
}
}
}
}
UpdatePUT/schemas/{schema_id}
A Schema
that has associate documents can be updated.
-
If a field is set from
indexed=False
toindexed=True
the schema and documents are reindexed. -
If a new field is added, the new documents have to contain the value for the new field, old documents will have the filed automatically set to
null
. -
It’s not possible to remove fields or remove indexing on a field.
Example URI
- schema_id
string
(required) Example: d88084ef-b6f7-405d-9863-d35b99543389String
id
of theSchema
.
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
Body
{
"description": "Test schema",
"structure": {
"fields": [
{
"name": "test",
"type": "integer"
},
{
"name": "test2",
"type": "integer"
}
]
}
}
200
Headers
Content-Type: application/json
Body
{
"result": "success",
"result_code": 200,
"message": null,
"data": {
"schema": {
"description": "Test schema",
"schema_id": "1323753e-0691-4649-81fd-fcb47f29b6fc",
"repository_id": "3ddba8af-6965-4416-9c5c-acf6af95539d",
"is_active": false,
"insert_date": "2015-02-13T18:23:20.287",
"last_update": "2015-02-24T23:05:15.394",
"structure": {
"fields": [
{
"type": "integer",
"name": "test"
},
{
"type": "integer",
"name": "test2"
}
]
}
}
}
}
UpdatePATCH/schemas/{schema_id}
With PATCH
the update is possible sending only partial information.
-
If a field is set from
indexed=False
toindexed=True
the schema and documents are reindexed. -
If a new field is added, the new documents have to contain the value for the new field, old documents will have the filed automatically set to
null
. -
It’s not possible to remove fields or remove indexing on a field.
Example URI
- schema_id
string
(required) Example: d88084ef-b6f7-405d-9863-d35b99543389String
id
of theSchema
.
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
Body
{
"description": "Test schema new"
}
200
Headers
Content-Type: application/json
Body
{
"result": "success",
"result_code": 200,
"message": null,
"data": {
"schema": {
"description": "Test schema new",
"schema_id": "1323753e-0691-4649-81fd-fcb47f29b6fc",
"repository_id": "3ddba8af-6965-4416-9c5c-acf6af95539d",
"is_active": false,
"insert_date": "2015-02-13T18:23:20.287",
"last_update": "2015-02-24T23:05:15.394",
"structure": {
"fields": [
{
"type": "integer",
"name": "test"
},
{
"type": "integer",
"name": "test2"
}
]
}
}
}
}
DeleteDELETE/schemas/{schema_id}?{force}&{all_content}
Caution
Deleting a Schema
will delete all the associated Documents
.
Example URI
- schema_id
string
(required) Example: d88084ef-b6f7-405d-9863-d35b99543389String
id
of theSchema
.- force
boolean
(optional) Example: trueTo force (
true
) the delete or to only deactivate (false
).- all_content
boolean
(optional) Example: trueWhen
true
, delete all the documents inside the schema (requires?force=true
).
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
200
Headers
Content-Type: application/json
Body
{
"result": "success",
"result_code": 200,
"data": null,
"message": null
}
Documents ¶
A Document is connected with a Schema
that defines its structure.
Documents ¶
ListGET/schemas/{schema_id}/documents{?full_document}
List of Documents
of the specified Schema
Example URI
- schema_id
string
(required) Example: d88084ef-b6f7-405d-9863-d35b99543389String
id
of theSchema
on which the user wants to create or get theDocuments
.- full_document
string
(optional) Example: trueIf the list should return the content of the doc. Default is
False
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
200
Headers
Content-Type: application/json
Body
{
"result": "success",
"result_code": 200,
"message": null,
"data": {
"count": 11,
"total_count": 11,
"limit": 100,
"offset": 0,
"documents": [
{
"repository_id": "3ddba8af-6965-4416-9c5c-acf6af95539d",
"insert_date": "2015-02-24T22:03:28.719",
"is_active": false,
"last_update": "2015-02-24T22:03:28.719",
"content": {},
"schema_id": "130b875a-d291-453e-8559-1b3c54500432",
"document_id": "c469d583-1e81-424e-b1ca-70822706dc5f"
},
{
"repository_id": "3ddba8af-6965-4416-9c5c-acf6af95539d",
"insert_date": "2015-02-23T15:40:23.572",
"is_active": false,
"last_update": "2015-02-23T15:40:23.572",
"content": {},
"schema_id": "130b875a-d291-453e-8559-1b3c54500432",
"document_id": "4f397edd-8891-4e03-9e49-869081656adf"
}
]
}
}
CreatePOST/schemas/{schema_id}/documents
To create a Document
the call expects the following fields:
- content (object, required) - the content of the document
The content
is a JSON object that must match the fields of the associated Schema
Note
There may be a delay between the document creation and the possibility to search for it (see search).
To overcome this you can specify in the URL this ?consistent=true
which will make the indexing synchronous with the post of the document. However, this operation has a cost and can make the post call to last for seconds before answering.
Use it only when it’s really needed.
Note
Fields can be set as empty by using the null
value.
Example URI
- schema_id
string
(required) Example: d88084ef-b6f7-405d-9863-d35b99543389String
id
of theSchema
on which the user wants to create or get theDocuments
.
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
Body
{
"content": {
"physician_id": "testId",
"physician_name": "Jack",
"observation": "The patient was ok.",
"visit_date": "2015-02-19 16:39:47"
}
}
200
Headers
Content-Type: application/json
Body
{
"result": "success",
"result_code": 200,
"message": null,
"data": {
"document": {
"document_id": "c373ba1a-1f23-4e36-a099-0ea3306b093d",
"repository_id": "3ddba8af-6965-4416-9c5c-acf6af95539d",
"schema_id": "130b875a-d291-453e-8559-1b3c54500432",
"insert_date": "2015-02-24T22:27:35.919",
"is_active": true,
"last_update": "2015-02-24T22:27:35.919",
}
}
}
Document object ¶
ReadGET/documents/{document_id}
Example URI
- document_id
string
(required) Example: d88084ef-b6f7-405d-9863-d35b99543389String
id
of theDocument
.
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
200
Headers
Content-Type: application/json
Body
{
"result": "success",
"result_code": 200,
"message": null,
"data": {
"document": {
"document_id": "c373ba1a-1f23-4e36-a099-0ea3306b093d",
"repository_id": "3ddba8af-6965-4416-9c5c-acf6af95539d",
"schema_id": "130b875a-d291-453e-8559-1b3c54500432",
"insert_date": "2015-02-24T22:27:35.919",
"is_active": true,
"last_update": "2015-02-24T22:27:35.919",
"content": {
"physician_id": "130b875a-d291-453e-8559-1b3c54500432",
"physician_name": "Jack",
"observation": "The patient was ok.",
"visit_date": "2015-02-19 16:39:47"
}
}
}
}
UpdatePUT/documents/{document_id}
Example URI
- document_id
string
(required) Example: d88084ef-b6f7-405d-9863-d35b99543389String
id
of theDocument
.
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
Body
{
"content": {
"physician_id": "testId",
"physician_name": "Jack",
"observation": "The patient died.",
"visit_date": "2015-02-19 16:39:47"
}
}
200
Headers
Content-Type: application/json
Body
{
"result": "success",
"result_code": 200,
"message": null,
"data": {
"document": {
"document_id": "c373ba1a-1f23-4e36-a099-0ea3306b093d",
"repository_id": "3ddba8af-6965-4416-9c5c-acf6af95539d",
"schema_id": "130b875a-d291-453e-8559-1b3c54500432",
"insert_date": "2015-02-24T22:27:35.919",
"is_active": true,
"last_update": "2015-02-24T22:27:35.919",
"content": {
"physician_id": "130b875a-d291-453e-8559-1b3c54500432",
"physician_name": "Jack",
"observation": "The patient died.",
"visit_date": "2015-02-19 16:39:47"
}
}
}
}
DeleteDELETE/documents/{document_id}{?force}
Note
You can use ?consistent=true
also for the delete operation.
Example URI
- document_id
string
(required) Example: d88084ef-b6f7-405d-9863-d35b99543389String
id
of theDocument
.- force
boolean
(optional) Example: trueTo force (
true
) the delete or to only deactivate (false
)
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
200
Headers
Content-Type: application/json
Body
{
"result": "success",
"result_code": 200,
"data": null,
"message": null
}
BLOBs ¶
BLOB API allows a user to upload large files using a chunked upload to provide reliable upload also in case of poor connectivity.
In this way uploading process can be resumed in case of connection interruption.
BLOBs
are attached to (or contained with) Document
fields. This allows storing many BLOBs
within a single Document
, and later on, to search for them and retrieve them easily.
Typical usage:
-
Create a BLOB
withdocument_id
,field_id
,filename
, and receive anupload_id
in return. -
Upload Chunks
using theupload_id
to identify the upload in progress. -
After submitting the last chunk, call the
Commit
call to close the upload.
Note
Upload chunk size can be from 100 KBytes to 50 MBytes.
A file upload process can last maximum 48 hours, afterwards it expires.
Create a Blob ¶
Create a BlobPOST/blobs
Start uploading a new BLOB
. Expected parameters are:
-
document_id: (string, required) - id of the
Document
associated. -
field: (string, required) - field where the blob is linked.
-
file_name (string, required) - the name of the blob file.
This operation returns an upload_id
that is used in the uploads of chunks.
Example URI
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
Body
{
"document_id": "40d12ace-c52d-4508-b887-23fa8d2825d7",
"field": "taken_pic",
"file_name": "imageXYZ.jpg"
}
200
Headers
Content-Type: application/json
Body
{
"result": "success",
"result_code": 200,
"message": null,
"data": {
"blob": {
"upload_id": "04c77007-b7f8-480f-b1c6-a16f4755cda2",
"expire_date": "2015-04-14T05:09:54.915Z",
}
}
}
Upload Blob Object ¶
Upload a ChunkPUT/blobs/{upload_id}
Upload a chunk. This operation is application/octet-stream
and expects data as Headers.
You can upload chunks in parallel and without order. The system takes into consideration the length
and offset
that are sent as headers.
Note
In the headers specify the length
and offset
of the chunk.
Example URI
- upload_id
string
(required) Example: 85c6b0f8-9033-4b9a-8457-617ec1adc0eeString
upload id
of theBlob
. It’s a temporary value used during the upload
Headers
Content-Type: application/octet-stream
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
offset: 200 (Offset of the chunk)
length: 100 (Length of the chunk)
Body
2xkIE1hY0RvbmFsZCBoYWQgYSBmYXJtCkUgSS
BFIEkgTwpBbmQgb24gaGlzIGZhcm0gaGUgaGFk
200
Headers
Content-Type: application/json
Body
{
"result": "success",
"result_code": 200,
"message": null,
"data": {
"blob": {
"expire_date": "2015-04-14T05:16:08.317Z",
"upload_id": "85c6b0f8-9033-4b9a-8457-617ec1adc0ee",
}
}
}
Commit Blob Object ¶
Commit BLOBPOST/blobs/commit
Complete the uploading process of a BLOB
.
This operation finalizes the BLOB
upload and returns a blob_id
that could be used in further operation.
Requires the upload_id
to be sent in the body.
Example URI
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
Body
{
"upload_id": "85c6b0f8-9033-4b9a-8457-617ec1adc0ee"
}
200
Headers
Content-Type: application/json
Body
{
"result": "success",
"result_code": 200,
"message": null,
"data": {
"blob": {
"bytes": 41231,
"blob_id": "85c6b0f8-9033-4b9a-8457-617ec1adc0ee",
"sha1": "89cfc89bc8a2197e9d1fdf653bb4d63bb7b7fd4d",
"document_id": "40d12ace-c52d-4508-b887-23fa8d2825d7",
"md5": "70a4479bdb5db0cf58184c7210ee07af"
}
}
}
Blob Object ¶
ReadGET/blobs/{blob_id}
Downloads the content of a BLOB encoded as application/octet-stream
.
Example URI
- blob_id
string
(required) Example: d88084ef-b6f7-405d-9863-d35b99543389String
id
of theBlob
.
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
200
Headers
Content-Type: application/json
Body
Content-Type: application/octet-stream
Content-Disposition: attachment; filename=imageXYZ.jpg
T2xkIE1hY0RvbmFsZCBoYWQgYSBmYXJtCkUgSS
BFIEkgTwpBbmQgb24gaGlzIGZhcm0gaGUgaGFk
IHNvbWUgZHVja3MKRSBJIEUgSSBPCldpdGggYS
BxdWFjayBxdWFjayBoZXJlLAphIHF1YWNrIHF1
YWNrIHRoZXJlLApldmVyeSB3aGVyZSBhIHF1YW
NrIHF1YWNrCkUgSSBFIEkgTwo=
DeleteDELETE/blobs/{blob_id}
Delete a BLOB file.
Caution
Deleted BLOBs cannot be restored.
Note
There’s no force
parameter. The calls delete the file from the storage of the server.
Example URI
- blob_id
string
(required) Example: d88084ef-b6f7-405d-9863-d35b99543389String
id
of theBlob
.
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
200
Body
{
"result": "success",
"result_code": 200,
"data": null,
"message": null
}
Collections ¶
Collections are groups of Documents.
Collections are not linked to a Repository or Schema: this allows a user to group Documents of different Repositories in one place.
Note
Collections support Permissions; it means that a User can see a Collection’s metadata and content
(Documents) only if they have R
Permissions on them.
Other than by ID, Collections are identified by their name
, that must be unique.
Collections ¶
ListGET/collections
Example URI
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
200
Body
{
"message": null,
"data": {
"count": 1,
"total_count": 1,
"limit": 100,
"collections": [
{
"collection_id": "de991a83-da39-4a72-a79e-1376124ebd57",
"last_update": "2016-02-08T11:05:26.571Z",
"is_active": true,
"name": "testCollection",
"insert_date": "2016-02-08T11:05:26.571Z"
}
],
"offset": 0
},
"result": "success",
"result_code": 200
}
CreatePOST/collections
Expected fields are:
- name: (string, required) - name of the collection. Must be unique in all your Collections.
Example URI
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
Body
{
"name": "testCollection"
}
200
Body
{
"message": null,
"data": {
"collection": {
"collection_id": "de991a83-da39-4a72-a79e-1376124ebd57",
"last_update": "2016-02-08T11:05:26.571Z",
"is_active": true,
"name": "testCollection",
"insert_date": "2016-02-08T11:05:26.571Z"
}
},
"result": "success",
"result_code": 200
}
Collection Object ¶
ReadGET/collections/{collection_id}
Example URI
- collection_id
string
(required) Example: de991a83-da39-4a72-a79e-1376124ebd57String
id
of theCollection
.
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
200
Body
{
"message": null,
"data": {
"collection": {
"collection_id": "de991a83-da39-4a72-a79e-1376124ebd57",
"last_update": "2016-02-08T11:05:26.571Z",
"is_active": true,
"name": "testCollection",
"insert_date": "2016-02-08T11:05:26.571Z"
}
},
"result": "success",
"result_code": 200
}
UpdatePUT/collections/{collection_id}
Example URI
- collection_id
string
(required) Example: de991a83-da39-4a72-a79e-1376124ebd57String
id
of theCollection
.
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
Body
{
"name": "testCollection_new"
}
200
Body
{
"message": null,
"data": {
"collection": {
"collection_id": "de991a83-da39-4a72-a79e-1376124ebd57",
"last_update": "2016-02-10T12:15:12.121Z",
"is_active": true,
"name": "testCollection_new",
"insert_date": "2016-02-08T11:05:26.571Z"
}
},
"result": "success",
"result_code": 200
}
DeleteDELETE/collections/{collection_id}{?force}
Example URI
- collection_id
string
(required) Example: de991a83-da39-4a72-a79e-1376124ebd57String
id
of theCollection
.- force
boolean
(optional) Example: trueTo force (
true
) the delete or to only deactivate (false
)
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
200
Body
{
"result": "success",
"result_code": 200,
"data": null,
"message": null
}
Collection list DocumentsGET/collections/{collection_id}/documents
Example URI
- collection_id
string
(required) Example: de991a83-da39-4a72-a79e-1376124ebd57String
id
of theCollection
.
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
Body
{
"name": "testCollection_new"
}
200
Headers
Content-Type: application/json
Body
{
"result": "success",
"result_code": 200,
"message": null,
"data": {
"count": 11,
"total_count": 11,
"limit": 100,
"offset": 0,
"documents": [
{
"repository_id": "3ddba8af-6965-4416-9c5c-acf6af95539d",
"insert_date": "2015-02-24T22:03:28.719",
"is_active": false,
"last_update": "2015-02-24T22:03:28.719",
"content": {},
"schema_id": "130b875a-d291-453e-8559-1b3c54500432",
"document_id": "c469d583-1e81-424e-b1ca-70822706dc5f"
},
{
"repository_id": "3ddba8af-6965-4416-9c5c-acf6af95539d",
"insert_date": "2015-02-23T15:40:23.572",
"is_active": false,
"last_update": "2015-02-23T15:40:23.572",
"content": {},
"schema_id": "130b875a-d291-453e-8559-1b3c54500432",
"document_id": "4f397edd-8891-4e03-9e49-869081656adf"
}
]
}
}
Collection and Documents ¶
Add a DocumentPOST/collections/{collection_id}/documents/{document_id}
Example URI
- collection_id
string
(required) Example: de991a83-da39-4a72-a79e-1376124ebd57String
id
of theCollection
.- document_id
string
(required) Example: 4f397edd-8891-4e03-9e49-869081656adfString
id
of theDocument
.
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
200
Headers
Content-Type: application/json
Body
{
"result": "success",
"result_code": 200,
"message": null,
"data": {}
}
Remove a DocumentDELETE/collections/{collection_id}/documents/{document_id}
Example URI
- collection_id
string
(required) Example: de991a83-da39-4a72-a79e-1376124ebd57String
id
of theCollection
.- document_id
string
(required) Example: 4f397edd-8891-4e03-9e49-869081656adfString
id
of theDocument
.
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
200
Headers
Content-Type: application/json
Body
{
"result": "success",
"result_code": 200,
"message": null,
"data": {}
}
Search ¶
Search a CollectionPOST/collections/search
Do you want to search Documents and Users instead?
Search a Collections by name.
Note
contains
is a boolean parameter that specifies if the value passed via the name
field is an exact match or if it has to be contained in the name.
Example URI
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
Body
{
"name": "foo",
"contains": true
}
200
Body
{
"message": null,
"data": {
"count": 2,
"total_count": 2,
"limit": 100,
"collections": [
{
"collection_id": "08fe5c40-18c0-4324-bb68-f34e7dcc55f9",
"last_update": "2016-02-22T13:07:59.743Z",
"is_active": true,
"name": "foo",
"insert_date": "2016-02-22T13:07:59.743Z"
},
{
"collection_id": "d51df22b-49c4-42c4-ad0a-2f450543d85e",
"last_update": "2016-02-22T13:07:59.746Z",
"is_active": true,
"name": "foo2",
"insert_date": "2016-02-22T13:07:59.746Z"
}
],
"offset": 0
},
"result": "success",
"result_code": 200
}
Search API ¶
Do you want to search a Collection by name instead?
Search API contains only the search
method and allows users to perform queries over Documents
of a given Schema
or Users
in a UserSchema
.
For security reasons, Chino.io provides a state-of-the-art mechanism to perform search operations without decrypting the content of Documents
and the information about Users
.
Note
There may be a delay between the creation of a Document or User and the possibility to search it (milliseconds). Chino.io indexing mechanism is asynchronous and it requires some processing before making the document available for the search operation. If you want to search immediately after the creation of a Document or a User then check the consistent option in POST Document operation, otherwise the new resource might not show up in the Search results.
Note
It’s not possible to return more than 5000 results for a Search. The 5000 limit is computed as the sum of the
offset
and the limit
parameters. Thus, if you have a search operation that could return more than 5000 Documents or Users you can only access the first 5000. Narrow down your search (e.g. using timestamps) to be able to see more data.
Search query
In order to perform a Search, you send a Search request to Chino.io, which consists of:
-
the
result_type
, i.e. the level of detail of the Search results (e.g. the full Document or only the ID) -
one or more criteria to
sort
the results. Specify afield
name and the sortorder
(asc/desc). -
the
query
itself.
{
"result_type": "FULL_CONTENT",
"sort": [
{
"field": "first_name",
"order": "asc"
},
{
"field": "last_name",
"order": "desc"
}
],
"query": {
"and": [
{
"field": "ticket_id",
"type": "eq",
"value": "b18814ae499621c2"
},
{
"field": "age",
"type": "gt",
"value": 10
}
]
}
}
Defining Search criteria
The structure of the Search query
is a JSON that can be composed of conditions and/or leaves.
-
a leaf is an object containing
field
,type
andvalue
-
a condition is one of the keys
and
,or
,not
followed by a list of other leaves and conditions.
Leaves contain the criteria that are used to filter the results. You specify the name of the field
you want to search,
the type
of filter you want to apply and the value
to compare.
FIELD
You can search:
-
in every field of a Document’s
content
and in everyattribute
of a User, as long as they have been created with"indexed": true
-
in the username of Users, which is indexed as
username
-
in the metadata of Users and Documents, which are indexed with a
_
prefix:_id
indexes thedocument_id
oruser_id
_schema_id
indexes theschema_id
(Documents) or theuser_schema_id
(Users)_insert_date
indexes theinsert_date
_last_update
indexes thelast_update
_is_active
indexes theis_active
{
"and": [
{
"field": "username",
"type": "eq",
"value": "james"
},
{
"field": "birth_date",
"type": "gte",
"value": "2019-01-06T10:53:38.157"
}
]
}
{
"and": [
{
"field": "username",
"type": "eq",
"value": "james"
},
{
"field": "birth_date",
"type": "gte",
"value": "2019-01-06T10:53:38.157"
}
]
}
FILTER OPERATORS
You can filter Documents and Users using one of the following operators as type
:
Operator | Meaning | Description |
---|---|---|
eq |
a = b |
exact match |
lt |
a < b |
lower than |
lte |
a <= b |
lower than or equal |
gt |
a > b |
greater than |
gte |
a >= b |
greater than or equal |
is |
a is true |
exact match (only for booleans) |
in |
a in [a, b, c] |
check against multiple values |
like |
"abc" like "a?*" |
regex (only for strings) |
Regex
You can use like
to search Strings that match a simple regular expression. You can use wildcards:
-
*
: matches any string - also the empty one; -
?
: matches any single char.
{
"field": "string_field",
"type": "like",
"value": "test?*"
}
Multiple values
You can specify a set of allowed values for the Search. Use the in
operator with the following syntax:
{
"field": "integer_field",
"type": "in",
"value": [1, 2, 3, 4, 5, 6, 7, 8, 9]
}
The general case is when you filter Documents
or User
that belong to a list of allowed IDs.
Search in arrays
If a resource has an array
field where at least one element satisfies the Search query, the Search is successful.
For example, the following query:
{
"field": "measures",
"type": "gte",
"value": 3.32
}
Might return a Document with this content:
{
"title": "Routine checkup",
"measures": [1.70, 0.85, 3.32]
}
See more examples below or skip to the next section
Examples
Leaf
last_name = "Smith"
{
"field": "last_name",
"type": "eq",
"value": "Smith"
}
Condition
last_name = "Smith" OR last_name = "Snow"
{
"or":[
{
"field": "last_name",
"type": "eq",
"value": "Smith"
},
{
"field": "last_name",
"type": "eq",
"value": "Snow"
}
]
}
Nested
last_name="Smith" AND (age > 60 OR age < 20)
{
"and": [{
"field": "last_name",
"type": "eq",
"value": "Smith"
},
{
"or": [{
"field": "age",
"type": "gt",
"value": 60
},
{
"field": "age",
"type": "lt",
"value": 20
}
]
}
]
}
Search result types
The calls to the Search API return in the data
field:
-
count
: the number of results that are returned. This is always returned. -
total_count
: the number of all the results that match the query. -
limit
: the number of results that the user requested (100 is max value) -
offset
: the number of results skipped before returning the list (e.g., useoffset=100
to return the second page when there are more than 100 results) -
a list of results, whose key and value is different according to the requested
result_type
:FULL_CONTENT
,NO_CONTENT
,ONLY_ID
,COUNT
,EXISTS
,USERNAME_EXISTS
.
The following examples show the different responses that you can get by changing the result_type
.
You can also skip to the Search API definition
FULL_CONTENT
(Users and Documents)
Return the whole Documents/Users that match the Search, included their content
or attributes
.
{
"result": "success",
"result_code": 200,
"message": null,
"data": {
"count": 2,
"total_count": 11,
"limit": 2,
"offset": 0,
"documents": [
{
"repository_id": "3ddba8af-6965-4416-9c5c-acf6af95539d",
"schema_id": "130b875a-d291-453e-8559-1b3c54500432",
"document_id": "c469d583-1e81-424e-b1ca-70822706dc5f",
"insert_date": "2015-02-24T22:03:28.719",
"is_active": false,
"last_update": "2015-02-24T22:03:28.719",
"content": {
"test": 555
}
},
...
]
}
}
NO_CONTENT
(Documents)
Return the Documents/Users without content
or attributes
. This query is faster since the results are not decrypted.
{
"result": "success",
"result_code": 200,
"message": null,
"data": {
"count": 2,
"total_count": 11,
"limit": 2,
"offset": 0,
"documents": [
{
"repository_id": "3ddba8af-6965-4416-9c5c-acf6af95539d",
"schema_id": "130b875a-d291-453e-8559-1b3c54500432",
"document_id": "c469d583-1e81-424e-b1ca-70822706dc5f",
"insert_date": "2015-02-24T22:03:28.719",
"is_active": false,
"last_update": "2015-02-24T22:03:28.719",
},
...
]
}
}
ONLY_ID
(Documents)
This query returns only the IDs of the Documents/Users that match the query.
{
"result": "success",
"result_code": 200,
"message": null,
"data": {
"total_count": 11,
"count": 11,
"limit": 100,
"offset":0,
"IDs": [
"c469d583-1e81-424e-b1ca-70822706dc5f",
"4f397edd-8891-4e03-9e49-869081656adf",
...
]
}
}
COUNT
(Documents and Users)
Return only a key count with the number of matching Documents/Users.
{
"result": "success",
"result_code": 200,
"message": null,
"data": {
"count": 11
}
}
EXISTS
(Users)
Return a flag that is true
only if at least one User exists that matches the Search query.
{
"result": "success",
"result_code": 200,
"message": null,
"data": {
"exists": true
}
}
USERNAME_EXISTS
(Users)
This result type can only be returned for a query in this format:
... ,
"query": {
"field": "username",
"type": "eq",
"value": "<some username>"
}
The structure of the response is the same as EXISTS
and will be true
only if a user named <some username>
exists
in the account.
Old Search API
Warning
The following features are deprecated. We suggest to use the new Search API, see above
The old Search system of Chino.io differs from above in that:
-
the
query
is replaced by the keyfilter
, which contains a list of search criteria (field
,type
,value
) -
you can specify exactly one
filter_type
, which can beand
,or
ornot
and defines how the criteria will be evaluated.
Example
{
"result_type": "FULL_CONTENT",
"filter_type": "and",
"sort": [
{
"field": "last_name",
"order": "asc"
}
],
"filter":[
{
"field": "last_name",
"type": "like",
"value": "A*"
},
{
"field": "age",
"type": "gte",
"value": "18"
}
]
}
Search Document ¶
Search DocumentPOST/search/documents/{schema_id}
Allowed values:
-
result_type
- mandatory :FULL_CONTENT
,NO_CONTENT
,ONLY_ID
orCOUNT
. What’s this? -
sort
- optional. The criteria for sorting the results; it may contain any of the schema fields. What’s this? -
query
- mandatory. The Search query to perform. What’s this?
Example URI
- schema_id
string
(required) Example: d88084ef-b6f7-405d-9863-d35b99543389String
id
of theSchema
.
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
Body
{
"result_type": "FULL_CONTENT",
"filter_type": "and",
"sort": [
{
"field": "first_name",
"order": "asc"
},
{
"field": "last_name",
"order": "desc"
}
],
"query": {
"and": [
{
"field": "last_name",
"type": "eq",
"value": "Smith"
},
{
"field": "age",
"type": "gt",
"value": 14
}
]
}
}
200
Headers
Content-Type: application/json
Body
{
"result": "success",
"result_code": 200,
"message": null,
"data": {
"count": 2,
"total_count": 2,
"limit": 10,
"offset": 0,
"documents": [
{
"repository_id": "3ddba8af-6965-4416-9c5c-acf6af95539d",
"schema_id": "130b875a-d291-453e-8559-1b3c54500432",
"document_id": "c469d583-1e81-424e-b1ca-70822706dc5f",
"insert_date": "2015-02-24T22:03:28.719",
"is_active": false,
"last_update": "2015-02-24T22:03:28.719",
"content": {
"first_name": "John",
"last_name": "Smith",
"age": 65
}
},
{
"repository_id": "3ddba8af-6965-4416-9c5c-acf6af95539d",
"schema_id": "130b875a-d291-453e-8559-1b3c54500432",
"document_id": "4f397edd-8891-4e03-9e49-869081656adf",
"insert_date": "2015-02-23T15:40:23.572",
"is_active": false,
"last_update": "2015-02-23T15:40:23.572",
"content": {
"first_name": "James",
"last_name": "Smith",
"age": 16
}
},
{
"repository_id": "3ddba8af-6965-4416-9c5c-acf6af95539d",
"schema_id": "130b875a-d291-453e-8559-1b3c54500432",
"document_id": "8e32ede-7712-4e01-7e45-4590323646vvf",
"insert_date": "2015-02-23T15:41:24.123",
"is_active": false,
"last_update": "2015-02-23T15:41:24.123",
"content": {
"first_name": "Jerome",
"last_name": "Smith",
"age": 43
}
}
]
}
}
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
Body
{
"result_type": "FULL_CONTENT",
"query": {
"and": [
{
"field": "last_name",
"type": "eq",
"value": "Smith"
},
{
"or": [
{
"field": "age",
"type": "gt",
"value": 60
},
{
"field": "age",
"type": "lt",
"value": 20
}
]
}
]
}
}
200
Headers
Content-Type: application/json
Body
{
"result": "success",
"result_code": 200,
"message": null,
"data": {
"count": 2,
"total_count": 2,
"limit": 10,
"offset": 0,
"documents": [
{
"repository_id": "3ddba8af-6965-4416-9c5c-acf6af95539d",
"schema_id": "130b875a-d291-453e-8559-1b3c54500432",
"document_id": "c469d583-1e81-424e-b1ca-70822706dc5f",
"insert_date": "2015-02-24T22:03:28.719",
"is_active": false,
"last_update": "2015-02-24T22:03:28.719",
"content": {
"first_name": "John",
"last_name": "Smith",
"age": 65
}
},
{
"repository_id": "3ddba8af-6965-4416-9c5c-acf6af95539d",
"schema_id": "130b875a-d291-453e-8559-1b3c54500432",
"document_id": "4f397edd-8891-4e03-9e49-869081656adf",
"insert_date": "2015-02-23T15:40:23.572",
"is_active": false,
"last_update": "2015-02-23T15:40:23.572",
"content": {
"first_name": "James",
"last_name": "Smith",
"age": 16
}
}
]
}
}
Search User ¶
Search UserPOST/search/users/{user_schema_id}
Perform a search operation on a set of fields within a user_schema_id
. It allows searching over Users.
-
result_type
- mandatory.FULL_CONTENT
,COUNT
,EXISTS
orUSERNAME_EXISTS
.What’s this? -
sort
- optional. The criteria for sorting the results; it may contain any of the schema fields. What’s this? -
query
- mandatory. The Search query to perform. What’s this?
Note
The password
is never returned in the results.
Example URI
- user_schema_id
string
(required) Example: aas84ef-b6f7-405d-9863-d35b99543389String
id
of theUserSchema
.
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
Body
{
"result_type": "FULL_CONTENT",
"sort": [
{
"field": "last_name",
"order": "desc"
}
],
"query": {
"and": [
{
"field": "username",
"type": "eq",
"value": "james"
},
{
"field": "last_name",
"type": "eq",
"value": "Smith"
}
]
}
}
200
Headers
Content-Type: application/json
Body
{
"message": null,
"data": {
"user": {
"username": "james",
"schema_id": "34321213-d6ac-472a-aee9-324243252454",
"user_id": "345457112-40df-4497-9a32-453453412131",
"insert_date": "2017-09-06T09:27:21.157Z",
"groups": [],
"attributes": {
"first_name": "James Edward"
"date_birth": "1960-01-01",
"last_name": "Smith"
},
"is_active": true,
"last_update": "2017-10-01T09:27:21.545Z"
}
},
"result": "success",
"result_code": 200
}
Changelog ¶
02/2019
-
ADD
Permissions over Collections -
ADD
new API to list all members of a Group -
ADD
Search by metadata for all resources
01/2019
ADD
new Search API to the documentation
07/2018
ADD
Search by metadata for Doc in DEV enviroment.
01/2018
ADD
Consent Management for tracking Users’ consent
12/2017
ADD
update
of UserSchema when not empty
11/2017
ADD
string compare operatorlike
for search over Documents.
10/2017
-
ADD
complex search for Documents -
ADD
null
value for fields -
ADD
update
of Schema when not empty
09/2017
-
ADD
Search Users: added search byusername
,_id
-
ADD
arrayfield
for both Schema and UserSchema -
Fixes and improvements
06/2017
Enable
theclient_type
02/2017
-
FIX
New values for limits -
ADD
consistent
parameter for User creation and delete -
ADD
in
operator for Search in arrays -
ADD
5000 items limit in Search. -
Fixes
10/2017
-
EDIT
Search Documents: new urls and format -
ADD
Search Users -
EDIT
Auth: now allows authentication in body or header -
ADD
consistent
for Document creation and delete -
Fixes
06/2017
ADD
differentclient_type
s for Applications (OAuth)
06/2016
-
EDIT
Auth: added OAuth parameters. -
ADD
Applications
02/2016
-
Fixes on the structure.
-
New layout.
-
ADD
Permissions -
ADD
Collections -
ADD
UserSchemas -
EDIT
BLOBs: added chunked upload