Back to top

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 to Schema 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. Run in 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 values success or error

  • 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 the public type it does not require to specify the client_secret in the requests

  • confidential: this type is for server side use of the Oauth where the client_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.

source

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 is public)

  • Chino.io returns and object with access_token and refresh_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 a callback url that points to a page he developed and that is able to get the code.

  • 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 the code that has to be used to get (parsing the URL from the server) the access_token and refresh_token

  • The developer application calls auth/token (to get the access_token and refresh_token. ) with:

    • 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"

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 Token
POST/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

POST https://api.chino.io/v1/auth/token/
Request  Password
HideShow
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`)
Request  Authorization code
HideShow
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"
Request  Refresh token
HideShow
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`)
Response  200
HideShow
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 Token
POST/auth/revoke_token/

Example URI

POST https://api.chino.io/v1/auth/revoke_token/
Request
HideShow
Headers
Content-Type: application/form-data
Body
token=<bearer_token>
client_id=<application_id>
client_secret=<application_secret>
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "result": "success",
  "result_code": 200,
  "message": null,
  "data": null
}

Get Info

Get the current session info.

Get Info
GET/users/me

Example URI

GET https://api.chino.io/v1/users/me
Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <Bearer-Token>
Response  200
HideShow
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

List
GET/auth/applications

Example URI

GET https://api.chino.io/v1/auth/applications
Request
HideShow
Headers
Content-Type: application/json
Authorization: Basic <Customer-Id>:<Customer-Key>
Response  200
HideShow
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"
      }
    ]
  }
}

Create
POST/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

POST https://api.chino.io/v1/auth/applications
Request
HideShow
Headers
Content-Type: application/json
Authorization: Basic <Customer-Id>:<Customer-Key>
Body
{
  "name": "Test",
  "grant_type": "password",
  "client_type": "confidential"
}
Response  200
HideShow
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

Read
GET/auth/applications/{application_id}

Example URI

GET https://api.chino.io/v1/auth/applications/lMcaHVNwqAuGulPIEj8voH3FQhMKPbj5GzShsxVL
URI Parameters
HideShow
application_id
string (required) Example: lMcaHVNwqAuGulPIEj8voH3FQhMKPbj5GzShsxVL

String id of the Application.

Request
HideShow
Headers
Content-Type: application/json
Authorization: Basic <Customer-Id>:<Customer-Key>
Response  200
HideShow
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
}

Update
PUT/auth/applications/{application_id}

Example URI

PUT https://api.chino.io/v1/auth/applications/lMcaHVNwqAuGulPIEj8voH3FQhMKPbj5GzShsxVL
URI Parameters
HideShow
application_id
string (required) Example: lMcaHVNwqAuGulPIEj8voH3FQhMKPbj5GzShsxVL

String id of the Application.

Request
HideShow
Headers
Content-Type: application/json
Authorization: Basic <Customer-Id>:<Customer-Key>
Body
{
  "name": "Test2",
  "grant_type": "password",
  "redirect_url": "http://127.0.0.1/"
}
Response  200
HideShow
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
}

Delete
DELETE/auth/applications/{application_id}

Example URI

DELETE https://api.chino.io/v1/auth/applications/lMcaHVNwqAuGulPIEj8voH3FQhMKPbj5GzShsxVL
URI Parameters
HideShow
application_id
string (required) Example: lMcaHVNwqAuGulPIEj8voH3FQhMKPbj5GzShsxVL

String id of the Application.

Request
HideShow
Headers
Content-Type: application/json
Authorization: Basic <Customer-Id>:<Customer-Key>
Response  200
HideShow
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

List
GET/user_schemas

List all the UserSchemas create for the account that is making the request.

Example URI

GET https://api.chino.io/v1/user_schemas
Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
Response  200
HideShow
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
}

Create
POST/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 of YYYY-MM-DD.

  • time - time in the form of HH:MM:SS.mmmmmm or HH:MM:SS.

  • datetime - datatime in the form of YYYY-MM-DDTHH:MM:SS.mmmmmm or YYYY-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 is true the field is indexed.

Example URI

POST https://api.chino.io/v1/user_schemas
Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
Body
{
  "description": "Encountersa",
  "structure": {
    "fields": [
      {
        "type": "string",
        "name": "test_string"
      }
    ]
  }
}
Response  200
HideShow
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

Read
GET/user_schemas/{user_schema_id}

Example URI

GET https://api.chino.io/v1/user_schemas/e87012ef-b6f7-405d-9863-d35b99543389
URI Parameters
HideShow
user_schema_id
string (required) Example: e87012ef-b6f7-405d-9863-d35b99543389

String id of the UserSchema.

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
Response  200
HideShow
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
}

Update
PUT/user_schemas/{user_schema_id}

Updates a user schema.

  • If a field is set from indexed=False to indexed=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

PUT https://api.chino.io/v1/user_schemas/e87012ef-b6f7-405d-9863-d35b99543389
URI Parameters
HideShow
user_schema_id
string (required) Example: e87012ef-b6f7-405d-9863-d35b99543389

String id of the UserSchema.

Request
HideShow
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"
      }
    ]
  }
}
Response  200
HideShow
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
}

Delete
DELETE/user_schemas/{user_schema_id}{?force}

Example URI

DELETE https://api.chino.io/v1/user_schemas/e87012ef-b6f7-405d-9863-d35b99543389?force=true
URI Parameters
HideShow
user_schema_id
string (required) Example: e87012ef-b6f7-405d-9863-d35b99543389

String id of the UserSchema.

force
boolean (optional) Example: true

To force (true) the delete or to only deactivate (false)

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
Response  200
HideShow
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

List
GET/user_schemas/{user_schema_id}/users

List all users that are created for the account that is making the request.

Example URI

GET https://api.chino.io/v1/user_schemas/e87012ef-b6f7-405d-9863-d35b99543389/users
URI Parameters
HideShow
user_schema_id
string (required) Example: e87012ef-b6f7-405d-9863-d35b99543389

String id of the UserSchema.

Request
HideShow
Headers
Content-Type: application/json
Authorization: Token <Access-Token> | <Customer-Id>:<Customer-Key>
Response  200
HideShow
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"
                ]
            }
            ...
        ]
    }
}

Create
POST/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

POST https://api.chino.io/v1/user_schemas/e87012ef-b6f7-405d-9863-d35b99543389/users
URI Parameters
HideShow
user_schema_id
string (required) Example: e87012ef-b6f7-405d-9863-d35b99543389

String id of the UserSchema.

Request
HideShow
Headers
Content-Type: application/json
Authorization: <Customer-Id>:<Customer-Key>
Body
{
  "username": "testUsernames",
  "password": "testPassword",
  "attributes": {
    "test_string": "test"
  },
  "is_active": true
}
Response  200
HideShow
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

Read
GET/users/{user_id}

Example URI

GET https://api.chino.io/v1/users/d88084ef-b6f7-405d-9863-d35b99543389
URI Parameters
HideShow
user_id
string (required) Example: d88084ef-b6f7-405d-9863-d35b99543389

String id of the User.

Request
HideShow
Headers
Content-Type: application/json
Authorization: <Customer-Id>:<Customer-Key>
Response  200
HideShow
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"
      ]
    }
  }
}

Update
PUT/users/{user_id}

Example URI

PUT https://api.chino.io/v1/users/d88084ef-b6f7-405d-9863-d35b99543389
URI Parameters
HideShow
user_id
string (required) Example: d88084ef-b6f7-405d-9863-d35b99543389

String id of the User.

Request
HideShow
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
    }
}
Response  200
HideShow
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 Update
PATCH/users/{user_id}

Updates can be done by specifying only some fields and not all.

Example URI

PATCH https://api.chino.io/v1/users/d88084ef-b6f7-405d-9863-d35b99543389
URI Parameters
HideShow
user_id
string (required) Example: d88084ef-b6f7-405d-9863-d35b99543389

String id of the User.

Request
HideShow
Headers
Content-Type: application/json
Authorization: Token <Access-Token> | <Customer-Id>:<Customer-Key>
Body
{
    "attributes": {
        "email": "james.ford@acme.com
    }
}
Response  200
HideShow
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"
      ]
    }
  }
}

Delete
DELETE/users/{user_id}{?force}

Note

You can use ?consistent=true also for the delete operation.

Example URI

DELETE https://api.chino.io/v1/users/d88084ef-b6f7-405d-9863-d35b99543389?force=true
URI Parameters
HideShow
user_id
string (required) Example: d88084ef-b6f7-405d-9863-d35b99543389

String id of the User.

force
boolean (optional) Example: true

To force (true) the delete or to only deactivate (false)

Request
HideShow
Headers
Content-Type: application/json
Authorization: <Customer-Id>:<Customer-Key>
Response  200
HideShow
Body
{
  "result": "success",
  "result_code": 200,
  "data": null,
  "message": null
}

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

List
GET/groups

List of all the groups that were created by the application

Example URI

GET https://api.chino.io/v1/groups
Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
Response  200
HideShow
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"
            }
        ]
    }
}

Create
POST/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 for Users) because the Group attributes are not indexed.

Example URI

POST https://api.chino.io/v1/groups
Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
Body
{
  "group_name": "Physicians",
  "attributes": {
    "hospital": "Main Hospital"
  }
}
Response  200
HideShow
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

Read
GET/groups/{group_id}

Example URI

GET https://api.chino.io/v1/groups/d88084ef-b6f7-405d-9863-d35b99543389
URI Parameters
HideShow
group_id
string (required) Example: d88084ef-b6f7-405d-9863-d35b99543389

String id of the Group.

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
Response  200
HideShow
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"
      }
    }
  }
}

Update
PUT/groups/{group_id}

Example URI

PUT https://api.chino.io/v1/groups/d88084ef-b6f7-405d-9863-d35b99543389
URI Parameters
HideShow
group_id
string (required) Example: d88084ef-b6f7-405d-9863-d35b99543389

String id of the Group.

Request
HideShow
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"
  }
}
Response  200
HideShow
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"
            }
        }
    }
}

Delete
DELETE/groups/{group_id}{?force}

Example URI

DELETE https://api.chino.io/v1/groups/d88084ef-b6f7-405d-9863-d35b99543389?force=true
URI Parameters
HideShow
group_id
string (required) Example: d88084ef-b6f7-405d-9863-d35b99543389

String id of the Group.

force
boolean (optional) Example: true

To force (true) the delete or to only deactivate (false)

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
Response  200
HideShow
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 members
POST/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

POST https://api.chino.io/v1/groups/d88084ef-b6f7-405d-9863-d35b99543389/users/d88084ef-b6f7-405d-9863-d35b99543389
URI Parameters
HideShow
group_id
string (required) Example: d88084ef-b6f7-405d-9863-d35b99543389

String id of the Group.

user_id
string (required) Example: d88084ef-b6f7-405d-9863-d35b99543389

String id of the User or UserSchema to add or remove.

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "result": "success",
  "result_code": 200,
  "message": null,
  "data": null
}

Remove members
DELETE/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

DELETE https://api.chino.io/v1/groups/d88084ef-b6f7-405d-9863-d35b99543389/users/d88084ef-b6f7-405d-9863-d35b99543389
URI Parameters
HideShow
group_id
string (required) Example: d88084ef-b6f7-405d-9863-d35b99543389

String id of the Group.

user_id
string (required) Example: d88084ef-b6f7-405d-9863-d35b99543389

String id of the User or UserSchema to add or remove.

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "result": "success",
  "result_code": 200,
  "data": null,
  "message": null
}

List Users
GET/groups/{group_id}/users

This call returns a list of all Users that have been added to the Group.

Example URI

GET https://api.chino.io/v1/groups/76cca5b6-dd9f-4d3b-8249-b8b23ca90b1b/users
URI Parameters
HideShow
group_id
string (required) Example: 76cca5b6-dd9f-4d3b-8249-b8b23ca90b1b

String id of the Group.

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
Response  200
HideShow
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 for data grants over Schema)

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 on Repository allows one to call the POST method to create a new Repository.

  • a R permission on Repository allows one to call the GET method to read the description of Repositories but not their content. Thus, the call returns the Repository description and not the contained Schema.

  • a R permission on Schema allows one to call the GET method to read the specified Schema. This call returns the Schema description, fields, and id but not the Documents. To read the Documents the application developer has to grant the permission on the child Resource (Document) of the specific Schema. (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.

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 a R 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 specified Schema

  • 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. Ex schema/72131278123.../documents, which is the grant on all the documents of the specified Schema.

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 Resources
POST/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

POST https://api.chino.io/v1/perms/grant/respositories/users/e00084ef-b6f7-42131-9863-d35b99543389
URI Parameters
HideShow
action
string (required) Example: grant

String can be grant or revoke.

resource_type
string (required) Example: respositories

String name of the Resource.

subject_type
string (required) Example: users

String can be users or groups.

subject_id
string (required) Example: e00084ef-b6f7-42131-9863-d35b99543389

String id the subject type identifier.

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
Body
{
  "manage": [
    "C"
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "result": "success",
  "result_code": 200,
  "message": null,
  "data": {}
}

Permissions on a Resource

Permission on a Resource
POST/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

POST https://api.chino.io/v1/perms/grant/schemas/d8sdf324ef-b6f7-405d-9863-d35b99543389/users/e00084ef-b6f7-42131-9863-d35b99543389
URI Parameters
HideShow
action
string (required) Example: grant

String can be grant or revoke.

resource_type
string (required) Example: schemas

String name of the Resource.

resource_id
string (required) Example: d8sdf324ef-b6f7-405d-9863-d35b99543389

String id of the Resource.

subject_type
string (required) Example: users

String can be users or groups.

subject_id
string (required) Example: e00084ef-b6f7-42131-9863-d35b99543389

String id the subject type identifier.

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
Body
{
  "manage": [
    "R"
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "result": "success",
  "result_code": 200,
  "message": null,
  "data": {}
}

Permission on Resource Children

Permission on Resource Children
POST/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):

resource type resource children manage authorize created_document
schemas documents R U D R U D A manage R U D
authorize R U D A
repositories schemas R U D R U D A n.a.
user_schemas users R U D R U D A n.a.

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

POST https://api.chino.io/v1/perms/grant/repositories/d8sdf324ef-b6f7-405d-9863-d35b99543389/schemas/groups/e00084ef-b6f7-42131-9863-d35b99543389
URI Parameters
HideShow
action
string (required) Example: grant

String can be grant or revoke.

resource_type
string (required) Example: repositories

String name of the Resource that his parent of the resource type.

resource_id
string (required) Example: d8sdf324ef-b6f7-405d-9863-d35b99543389

String id of the Parent.

resource_child_type
string (required) Example: schemas

String name of the Resource on which grants are applied

subject_type
string (required) Example: groups

String can be users or groups.

subject_id
string (required) Example: e00084ef-b6f7-42131-9863-d35b99543389

String id the subject type identifier.

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
Body
{
  "manage": [
    "C"
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "result": "success",
  "result_code": 200,
  "message": null,
  "data": {}
}

Read Permissions on all Resources

Read Permissions on all Resources
GET/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

GET https://api.chino.io/v1/perms
Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
Response  200
HideShow
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 Document
GET/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

GET https://api.chino.io/v1/perms/documents/c469d583-1e81-424e-b1ca-70822706dc5f
URI Parameters
HideShow
document_id
string (required) Example: c469d583-1e81-424e-b1ca-70822706dc5f

id of the Document

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
Response  200
HideShow
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 User
GET/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

GET https://api.chino.io/v1/perms/users/119083b6-19d-1000-a100-426114272730
URI Parameters
HideShow
user_id
string (required) Example: 119083b6-19d-1000-a100-426114272730

id of the User

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
Response  200
HideShow
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 Group
GET/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

GET https://api.chino.io/v1/perms/groups/3322383b6-19d-1800-a100-516113322730
URI Parameters
HideShow
group_id
string (required) Example: 3322383b6-19d-1800-a100-516113322730

id of the Group

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
Response  200
HideShow
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

List
GET/repositories

Example URI

GET https://api.chino.io/v1/repositories
Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
Response  200
HideShow
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"
      }
    ]
  }
}

Create
POST/repositories

The create operation expects the following parameter:

  • description (string, required) - the description of the Repository

Example URI

POST https://api.chino.io/v1/repositories
Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
Body
{
  "description": "This is a test repo"
}
Response  200
HideShow
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

Read
GET/repositories/{repository_id}

Example URI

GET https://api.chino.io/v1/repositories/d88084ef-b6f7-405d-9863-d35b99543389
URI Parameters
HideShow
repository_id
string (required) Example: d88084ef-b6f7-405d-9863-d35b99543389

String id of the Repository.

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
Response  200
HideShow
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"
    }
  }
}

Update
PUT/repositories/{repository_id}

Example URI

PUT https://api.chino.io/v1/repositories/d88084ef-b6f7-405d-9863-d35b99543389
URI Parameters
HideShow
repository_id
string (required) Example: d88084ef-b6f7-405d-9863-d35b99543389

String id of the Repository.

Request
HideShow
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
}
Response  200
HideShow
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"
    }
  }
}

Delete
DELETE/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

DELETE https://api.chino.io/v1/repositories/d88084ef-b6f7-405d-9863-d35b99543389?force=true
URI Parameters
HideShow
repository_id
string (required) Example: d88084ef-b6f7-405d-9863-d35b99543389

String id of the Repository.

force
boolean (optional) Example: true

To force (true) the delete or to only deactivate (false)

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
Response  200
HideShow
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 of YYYY-MM-DD.

  • time - time in the form of HH:MM:SS.mmmmmm or HH:MM:SS.

  • datetime - datetime in the form of YYYY-MM-DDTHH:MM:SS.mmmmmm or YYYY-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.

List
GET/repositories/{repository_id}/schemas

The list of schemas within the specified Repository

Example URI

GET https://api.chino.io/v1/repositories/d88084ef-b6f7-405d-9863-d35b99543389/schemas
URI Parameters
HideShow
repository_id
string (required) Example: d88084ef-b6f7-405d-9863-d35b99543389

String id of the Repository on which the user wants to get the schemas.

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
Response  200
HideShow
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
                        }
                    ]
                }
            }
        ]
    }
}

Create
POST/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 fields

    • fields: (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

POST https://api.chino.io/v1/repositories/d88084ef-b6f7-405d-9863-d35b99543389/schemas
URI Parameters
HideShow
repository_id
string (required) Example: d88084ef-b6f7-405d-9863-d35b99543389

String id of the Repository on which the user wants to get the schemas.

Request
HideShow
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
      }
    ]
  }
}
Response  200
HideShow
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

Read
GET/schemas/{schema_id}

Example URI

GET https://api.chino.io/v1/schemas/d88084ef-b6f7-405d-9863-d35b99543389
URI Parameters
HideShow
schema_id
string (required) Example: d88084ef-b6f7-405d-9863-d35b99543389

String id of the Schema.

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
Response  200
HideShow
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"
          }
        ]
      }
    }
  }
}

Update
PUT/schemas/{schema_id}

A Schema that has associate documents can be updated.

  • If a field is set from indexed=False to indexed=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

PUT https://api.chino.io/v1/schemas/d88084ef-b6f7-405d-9863-d35b99543389
URI Parameters
HideShow
schema_id
string (required) Example: d88084ef-b6f7-405d-9863-d35b99543389

String id of the Schema.

Request
HideShow
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"
      }
    ]
  }
}
Response  200
HideShow
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"
          }
        ]
      }
    }
  }
}

Update
PATCH/schemas/{schema_id}

With PATCH the update is possible sending only partial information.

  • If a field is set from indexed=False to indexed=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

PATCH https://api.chino.io/v1/schemas/d88084ef-b6f7-405d-9863-d35b99543389
URI Parameters
HideShow
schema_id
string (required) Example: d88084ef-b6f7-405d-9863-d35b99543389

String id of the Schema.

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
Body
{
  "description": "Test schema new"
}
Response  200
HideShow
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"
          }
        ]
      }
    }
  }
}

Delete
DELETE/schemas/{schema_id}?{force}&{all_content}

Caution

Deleting a Schema will delete all the associated Documents.

Example URI

DELETE https://api.chino.io/v1/schemas/d88084ef-b6f7-405d-9863-d35b99543389?true&true
URI Parameters
HideShow
schema_id
string (required) Example: d88084ef-b6f7-405d-9863-d35b99543389

String id of the Schema.

force
boolean (optional) Example: true

To force (true) the delete or to only deactivate (false).

all_content
boolean (optional) Example: true

When true, delete all the documents inside the schema (requires ?force=true).

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
Response  200
HideShow
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

List
GET/schemas/{schema_id}/documents{?full_document}

List of Documents of the specified Schema

Example URI

GET https://api.chino.io/v1/schemas/d88084ef-b6f7-405d-9863-d35b99543389/documents?full_document=true
URI Parameters
HideShow
schema_id
string (required) Example: d88084ef-b6f7-405d-9863-d35b99543389

String id of the Schema on which the user wants to create or get the Documents.

full_document
string (optional) Example: true

If the list should return the content of the doc. Default is False

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
Response  200
HideShow
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"
      }
    ]
  }
}

Create
POST/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

POST https://api.chino.io/v1/schemas/d88084ef-b6f7-405d-9863-d35b99543389/documents
URI Parameters
HideShow
schema_id
string (required) Example: d88084ef-b6f7-405d-9863-d35b99543389

String id of the Schema on which the user wants to create or get the Documents.

Request
HideShow
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"
  }
}
Response  200
HideShow
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

Read
GET/documents/{document_id}

Example URI

GET https://api.chino.io/v1/documents/d88084ef-b6f7-405d-9863-d35b99543389
URI Parameters
HideShow
document_id
string (required) Example: d88084ef-b6f7-405d-9863-d35b99543389

String id of the Document.

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
Response  200
HideShow
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"
      }
    }
  }
}

Update
PUT/documents/{document_id}

Example URI

PUT https://api.chino.io/v1/documents/d88084ef-b6f7-405d-9863-d35b99543389
URI Parameters
HideShow
document_id
string (required) Example: d88084ef-b6f7-405d-9863-d35b99543389

String id of the Document.

Request
HideShow
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"
  }
}
Response  200
HideShow
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"
      }
    }
  }
}

Delete
DELETE/documents/{document_id}{?force}

Note

You can use ?consistent=true also for the delete operation.

Example URI

DELETE https://api.chino.io/v1/documents/d88084ef-b6f7-405d-9863-d35b99543389?force=true
URI Parameters
HideShow
document_id
string (required) Example: d88084ef-b6f7-405d-9863-d35b99543389

String id of the Document.

force
boolean (optional) Example: true

To force (true) the delete or to only deactivate (false)

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
Response  200
HideShow
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 with document_id, field_id, filename, and receive an upload_id in return.

  • Upload Chunks using the upload_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 Blob
POST/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

POST https://api.chino.io/v1/blobs
Request
HideShow
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"
}
Response  200
HideShow
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 Chunk
PUT/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

PUT https://api.chino.io/v1/blobs/85c6b0f8-9033-4b9a-8457-617ec1adc0ee
URI Parameters
HideShow
upload_id
string (required) Example: 85c6b0f8-9033-4b9a-8457-617ec1adc0ee

String upload id of the Blob. It’s a temporary value used during the upload

Request
HideShow
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
Response  200
HideShow
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 BLOB
POST/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

POST https://api.chino.io/v1/blobs/commit
Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
Body
{
  "upload_id": "85c6b0f8-9033-4b9a-8457-617ec1adc0ee"
}
Response  200
HideShow
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

Read
GET/blobs/{blob_id}

Downloads the content of a BLOB encoded as application/octet-stream.

Example URI

GET https://api.chino.io/v1/blobs/d88084ef-b6f7-405d-9863-d35b99543389
URI Parameters
HideShow
blob_id
string (required) Example: d88084ef-b6f7-405d-9863-d35b99543389

String id of the Blob.

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
Response  200
HideShow
Headers
Content-Type: application/json
Body
Content-Type: application/octet-stream
Content-Disposition: attachment; filename=imageXYZ.jpg

T2xkIE1hY0RvbmFsZCBoYWQgYSBmYXJtCkUgSS
BFIEkgTwpBbmQgb24gaGlzIGZhcm0gaGUgaGFk
IHNvbWUgZHVja3MKRSBJIEUgSSBPCldpdGggYS
BxdWFjayBxdWFjayBoZXJlLAphIHF1YWNrIHF1
YWNrIHRoZXJlLApldmVyeSB3aGVyZSBhIHF1YW
NrIHF1YWNrCkUgSSBFIEkgTwo=

Delete
DELETE/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

DELETE https://api.chino.io/v1/blobs/d88084ef-b6f7-405d-9863-d35b99543389
URI Parameters
HideShow
blob_id
string (required) Example: d88084ef-b6f7-405d-9863-d35b99543389

String id of the Blob.

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
Response  200
HideShow
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

List
GET/collections

Example URI

GET https://api.chino.io/v1/collections
Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
Response  200
HideShow
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
}

Create
POST/collections

Expected fields are:

  • name: (string, required) - name of the collection. Must be unique in all your Collections.

Example URI

POST https://api.chino.io/v1/collections
Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
Body
{
  "name": "testCollection"
}
Response  200
HideShow
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

Read
GET/collections/{collection_id}

Example URI

GET https://api.chino.io/v1/collections/de991a83-da39-4a72-a79e-1376124ebd57
URI Parameters
HideShow
collection_id
string (required) Example: de991a83-da39-4a72-a79e-1376124ebd57

String id of the Collection.

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
Response  200
HideShow
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
}

Update
PUT/collections/{collection_id}

Example URI

PUT https://api.chino.io/v1/collections/de991a83-da39-4a72-a79e-1376124ebd57
URI Parameters
HideShow
collection_id
string (required) Example: de991a83-da39-4a72-a79e-1376124ebd57

String id of the Collection.

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
Body
{
  "name": "testCollection_new"
}
Response  200
HideShow
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
}

Delete
DELETE/collections/{collection_id}{?force}

Example URI

DELETE https://api.chino.io/v1/collections/de991a83-da39-4a72-a79e-1376124ebd57?force=true
URI Parameters
HideShow
collection_id
string (required) Example: de991a83-da39-4a72-a79e-1376124ebd57

String id of the Collection.

force
boolean (optional) Example: true

To force (true) the delete or to only deactivate (false)

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
Response  200
HideShow
Body
{
  "result": "success",
  "result_code": 200,
  "data": null,
  "message": null
}

Collection list Documents
GET/collections/{collection_id}/documents

Example URI

GET https://api.chino.io/v1/collections/de991a83-da39-4a72-a79e-1376124ebd57/documents
URI Parameters
HideShow
collection_id
string (required) Example: de991a83-da39-4a72-a79e-1376124ebd57

String id of the Collection.

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
Body
{
  "name": "testCollection_new"
}
Response  200
HideShow
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 Document
POST/collections/{collection_id}/documents/{document_id}

Example URI

POST https://api.chino.io/v1/collections/de991a83-da39-4a72-a79e-1376124ebd57/documents/4f397edd-8891-4e03-9e49-869081656adf
URI Parameters
HideShow
collection_id
string (required) Example: de991a83-da39-4a72-a79e-1376124ebd57

String id of the Collection.

document_id
string (required) Example: 4f397edd-8891-4e03-9e49-869081656adf

String id of the Document.

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "result": "success",
  "result_code": 200,
  "message": null,
  "data": {}
}

Remove a Document
DELETE/collections/{collection_id}/documents/{document_id}

Example URI

DELETE https://api.chino.io/v1/collections/de991a83-da39-4a72-a79e-1376124ebd57/documents/4f397edd-8891-4e03-9e49-869081656adf
URI Parameters
HideShow
collection_id
string (required) Example: de991a83-da39-4a72-a79e-1376124ebd57

String id of the Collection.

document_id
string (required) Example: 4f397edd-8891-4e03-9e49-869081656adf

String id of the Document.

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <bearer_token> | Basic <Customer-Id>:<Customer-Key>
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "result": "success",
  "result_code": 200,
  "message": null,
  "data": {}
}

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 a field name and the sort order (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 and value

  • 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 every attribute 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 the document_id or user_id
    • _schema_id indexes the schema_id (Documents) or the user_schema_id (Users)
    • _insert_date indexes the insert_date
    • _last_update indexes the last_update
    • _is_active indexes the is_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., use offset=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 key filter, which contains a list of search criteria (field, type, value)

  • you can specify exactly one filter_type, which can be and, or or not 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 Document
POST/search/documents/{schema_id}

Allowed values:

  • result_type - mandatory :FULL_CONTENT, NO_CONTENT, ONLY_ID or COUNT. 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

POST https://api.chino.io/v1/search/documents/d88084ef-b6f7-405d-9863-d35b99543389
URI Parameters
HideShow
schema_id
string (required) Example: d88084ef-b6f7-405d-9863-d35b99543389

String id of the Schema.

Request
HideShow
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
      }
    ]
  }
}
Response  200
HideShow
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
        }
      }
    ]
  }
}
Request
HideShow
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
          }
        ]
      }
    ]
  }
}
Response  200
HideShow
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 User
POST/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 or USERNAME_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

POST https://api.chino.io/v1/search/users/aas84ef-b6f7-405d-9863-d35b99543389
URI Parameters
HideShow
user_schema_id
string (required) Example: aas84ef-b6f7-405d-9863-d35b99543389

String id of the UserSchema.

Request
HideShow
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"
      }
    ]
  }
}
Response  200
HideShow
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 operator like 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 by username, _id

  • ADD arrayfield for both Schema and UserSchema

  • Fixes and improvements

06/2017

  • Enable the client_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 different client_types 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