Back to top

CHINO API Docs

CHINO API securely store privacy sensitive data of applications and their users according to EU Laws.

CHINO 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 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 to 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 set 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 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 offers a series of RESTful operations that implement the CRUD (Create, Read, Update, Delete) paradigm.

The SDKs

We have implemented SDK and wrappers for Python, Java, and C#. You can find the libraries on our github page.

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

  • 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 temporary 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 loose the data, so don’t use the HTTP protocol. CHINO 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", #at least 8 chars
            "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 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": {} //content of the answer
}

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 contains 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 maxium value of 100. Yet, the maximum value will be set to 10 in the near future.

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 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]

  • authorization code: In which the user is presented with the chino 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.

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 application-id and application-secret in the authorization and username and password in the body.

  • Chino 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 (which support 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 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 redirects the browser to the callback-url appending in the url the code that has to be used to retreive the access_token and refresh_token

  • The developer application sends the code and other information to chino (auth/token) to retreive the tokens.

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

Note

For the auth you either provide <Application-Id>:<Application-Secret> as Basic Auth or set client_id and client_secret in the body.

Use this wisely, try to not expose too many data to the client side.

Example URI

POST https://api.chino.io/v1/auth/token/
Request  Password
HideShow
Headers
Content-Type: multipart/form-data
Authorization: Basic <Application-Id>:<Application-Secret>
Body
grant_type=password
username=<username>
password=<password>
Request  Authorization code
HideShow
Headers
Content-Type: multipart/form-data
Body
grant_type=authorization_code
code=<code>
redirect_uri=<redirect_url>
client_id=<application_id>
client_secret=<application_secret>
scope=read write
Request  Refresh token
HideShow
Headers
Content-Type: multipart/form-data
Body
grant_type=refresh_token,
refresh_token=<refresh_token>,
client_id=<application_id>,
client_secret=<application_secret>
Response  200
HideShow
Headers
Content-Type: multipart/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: multipart/form-data
Body
token=<bearer_token>
client_id=<application_id>
client_secret=<application_secret>
Response  200
HideShow
Headers
Content-Type: multipart/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: multipart/json
Authorization: Baerer <Bearer-Token>
Response  200
HideShow
Headers
Content-Type: multipart/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.

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": "authorization-code",
  "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": "authorization-code",
      "app_name": "Test",
      "redirect_url": "http://127.0.0.1/",
      "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": "authorization-code",
      "app_name": "Teest",
      "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": "Tesst",
  "grant_type": "authorization-code",
  "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": "authorization-code",
      "app_name": "Tesst",
      "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 to UserSchemas. If a UserSchema has groups associated then each User crated within that UserSchema will be added to the Groups. To associate a Group to a Schema see the API in the Group section.

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

  • float - Float numbers

  • string - String limited to 255 chars.

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

Note

UserSchema can be updated only when there are no Users associated.

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 Developer account, thus they can be used in any repository that belongs to the Application Developer 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",
                "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",
                "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

  • password (string, required) - password for the login.

  • attributes (object, required) - attributes of the user. The content must match the UserSchema definition

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.

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

User API allows on to create, retrieve, update, delete a Group.

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",
                "groupname": "group1426263987562",
                "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",
                "groupname": "group1426263983102",
                "attributes": null,
                "group_id": "1eb39c88-3ac8-4664-b897-849dd260c72b"
            }
        ]
    }
}

Create
POST/groups

Create Group API requires a groupname that has to bee unique and accepts any additional information within the node attributes, like for Users.

Expected parameters are

  • groupname: (string, required) - Name of the group

  • attributes (object, optional) - Object containing attributes that are stored as additional information.

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
{
  "groupname": "PhysiciansXYZ",
  "attributes": {
    "hospital": "Main Hospital"
  }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "result": "success",
    "result_code": 200,
    "message": null,
    "data": {
        "group": {
            "groupname": "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": {
                "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": {
      "groupname": "pysiciansXY",
      "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
{
  "groupname": "PhysiciansXYZW",
  "is_active": true,
  "attributes": {
    "role": "oncologyst",
    "hospital": "Main Hospital"
  }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "result": "success",
    "result_code": 200,
    "message": null,
    "data": {
        "group": {
            "groupname": "PhysiciansXYZW",
            "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": "oncologyst",
                "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 a User/UserSchema to Group
POST/groups/{group_id}/users/{user_id}

Adds the specified User or UserSchema to the specified Group

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 a User/UserSchema from a Group
DELETE/groups/{group_id}/users/{user_id}

Deletes the specified User or UserSchema from a Group.

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
}

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 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 this value can be used for specifying grants over a Schema type object.

The permission is granted by by adding the S grant in the manage or authorize.

Grants on Created Documents

When a new document is created within a Schema we have to define the grants that are given to the person who has created the document (which we call Alice). By default Alice has no rights over her new document. To specify the default rights Chino has a field created_document which is must be specified in the call for the authorization of the schema.

The syntax is:

{
    "manage":["C", "L", "R", "U", "D", "S"],
    "authorize":["C", "L", "R", "U", "D", "S", "A"],
    "created_document":{
        "manage":["R", "U", "D"],
        "authorize":["R", "U", "D", "A"]
     }
}

In the example above when Alice creates a document she get RUD over it and the possibility to authorize RUDA over that document.

Note

The rights on the Documents of a Schema (schemas/<schema_id>/documents) manage:["C", "L", "R", "U", "D", "S"] gives to Alice the "C", "L", "R", "U", "D", "S" on all the documents of the Schema. In an example like the one above, the created_document rights are not needed, since she already has the rights on all the docs. In a case where the manage is only C Alice would have need the permission. In fact, Alice can create a document (she has C on Schema) and then have RUD over the document (rights on created_documents). If Alice has also the L permission over the Schema then she can perform a list on the Schema and will get back all the documents she created (or have any rights on it)

The Calls

We have three calls:

  • Resources: this one specify 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 specify 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 specify 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 specify 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.

Resource Structure

To understand the permission we have built a table that explains the gerarcy of the resources:

Top level 2nd level 3rd level
Group
UserSchema User
Repository Schema Document

Permission on Resources

Permission on Resources
POST/perms/{action}/{resource_type}/{subject_type}/{subject_id}

This calls specify the permission over resources of a specific type.

This call can be used only for the Top Level:

  • Groups

  • UserSchema

  • Repository

Example to grant to a group of users permission over all the Repositories.

  • resource_type: repositories

  • subject_type: groups

  • subject_id: <id_group_doc> // the id of the group we want to give the grant

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": {}
}

Perms

Permission on a Resource
POST/perms/{action}/{resource_type}/{resource_id}/{subject_type}/{subject_id}

This calls specify the permission over a specific resource.

This call can be used for all the resources

Example to grant to a group of users permission over a specific repository.

  • resource_type: repositories

  • resource_id: <id_repository>

  • subject_type: groups

  • subject_id: <id_group_doc> // the id of the group we want to give the grant

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 specify the permission over all the children of a specific resource.

This call can be used only with parent-child relation that is anything that is sequential in the table above. Ex: Repository and Schema or Schema and Document but not Repository and Document.

Example to grant to a group of users permission over all the schemas of a specific repository.

  • resource_type: repositories

  • resource_id: <id_repository>

  • resource_child_type: schemas

  • subject_type: groups

  • subject_id: <id_group_doc>

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 :)

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

Schemas

Schemas define the structure of Documents. The following are the types of data fields that are supported:

  • integer - Integer numbers

  • float - Float numbers

  • string - String limited to 255 chars.

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

  • blob - Placeholder for Blob uploads. See Blob section for more details.

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.

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: (array[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}

Note

A Schema that has associate documents cannot be updated.

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": "provaSchema",
      "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?force=true&all_content=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

To force (true) the delete of the documents inside the schema (require 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 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 raelly needed.

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, aftwards 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. A collection does not enforce a schema. Documents within a collection can have different schema.

Note

Collections are not linked to the Repository. This allow a user to group documents of different repositories in one place.

Name of the collection 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

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

Search API contains only the search method and allows users to perform queries over Documents of a certain Schema. For security reasons, CHINO provides a state-of-the-art mechanism to perform search operations without decrypting user’s Documents.

Note

There may be a delay between the document creation and the possibility to search for it. Chino implements an index that require processing before making the document available for the search. This operation requires some time to build the index of the document.

Note

It’s not possible to return more than 5000 results for a search. The 5000 value is computed as the sum of the offset and the limit. Thus, if you have a search operation that could return more than 5000 documents or user you can only access the first 5000. Narrow your search (e.g. using timestamps) to be able to access the data.

Filter

For the filtering we currently implement the following logics:

  • eq: (=) equal, if the value is the same as the one specified.

  • lt: (<) less than

  • lte: (<=) less than or equal

  • gt: (>) greater than

  • gte: (>=) greater than or equal

  • is: (=) only for boolean

  • in: if the value is contained in the list. (still experimental)

for the in filter the syntax is the following

{
    "field": "integer",
    "type": "in",
    "value": [1, 2, 3, 4, 5, 6, 7, 8, 9]
}

The general case is to search Documents or User via IDs

Note

We do not provide direct filtering for not (!=), not in (value not in list) for performance reason (in is still sperimental). You may mimic the same beahviour by combining query with the allowed filter, (e.g. lt and gt on the same value). Note that this query may take a long time to be computed and result in a timeout.

Search Document

Search Document
POST/search/documents/{schema_id}

Perform a search operation on a set of fields within a schema_id.

  • result_type - mandatory. It can be FULL_CONTENT for full docs, NO_CONTENT for headers only, ONLY_ID for list of ids, COUNT for the number of records only.

  • filter_type - mandatory. It can be and or or based on the logic you want to apply to search parameters.

  • sort - optional. It is used to define sorting of results. It can contain any of the schema fields.

  • filter - mandatory. The definiton of the search.

Note

You can still use the old format /search/{schema_id} for the url

Note

The schema_id can be removed from the url and set in the body as a parameter

TYPE OF RESULTS

We provide 4 type of results for the query on Documents:

FULL_CONTENT

This result returns the whole document and also its content. In the data there are also present the values of:

  • count: the number of elements in the result list that is inside Documents

  • total_count: the number of all the Documents that match the query.

  • limit: the number of results that the user wants in the list (limited to 100 as max value)

  • offset: the initial recrod from which the result list is computed (e.g., offset=100 returns the second page)

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

It’s the same as the case above, except the fact that the content is empty. This query is faster than the one with content since document are not decrypted but only meta-datas are rerturned.

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

This query returns the IDs of the document 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

{
 "result": "success",
 "result_code": 200,
 "message": null,
 "data": {
     "count": 11
 }
}

This query returns only the number of elements that match the query.

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"
    }
  ],
  "filter": [
    {
      "field": "last_name",
      "type": "eq",
      "value": "Smith"
    },
    {
      "field": "age",
      "type": "gt",
      "value": 6
    },
    {
      "field": "age",
      "type": "lt",
      "value": 6
    },
    {
      "field": "age",
      "type": "gte",
      "value": 6
    },
    {
      "field": "age",
      "type": "lte",
      "value": 6
    }
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "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
        }
      },
      {
        "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": {
          "test": 555
        }
      }
    ]
  }
}

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 to seach over Users.

  • result_type - mandatory. It can be FULL_CONTENT for full docs, COUNT for headers only, EXISTS for list of ids, USERNAME_EXISTS for the number of records only.

  • filter_type - mandatory. It can be and or or based on the logic you want to apply to search parameters.

  • sort - optional. It is used to define sorting of results. It can contain any of the schema fields.

  • filter - mandatory. The definiton of the search.

Note

Password is not shown in the results.

Note

The schema_id can be removed from the url and set in the body as a parameter

TYPE OF RESULTS

COUNT

Same as for the document search

FULL_CONTENT

Same as for the document search

EXISTS

Returns a True if one or more users matches the query, False otherwise.

USERNAME_EXISTS

Returns a True if the username already exists, False otherwise.

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.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "result": "success",
    "result_code": 200,
    "message": null,
    "data": {
        "count": 2,
        "total_count": 11,
        "limit": 2,
        "offset": 0,
        "users": [
            {
                ..
            },
            {
                ..
            }
        ]
    }
}

Changelog

02/2017

  • FIX New values for limits

  • ADD consistent for User creation and delete

  • IN for search

  • ADD explanation for the 5000 limit in search.

  • Fixes

10/2016

  • EDIT Document Search: new urls and format

  • ADD User Search

  • EDIT Auth: now allows authentication in body or header

  • ADD consistent for Document creation and delete

  • Fixes

06/2016

  • EDIT Auth: breaks old login.

  • ADD Applications

03/2016

  • Fixes on the structure.

02/2016

  • New layout.

  • ADD Permission

  • ADD Collection

  • ADD UserSchema

  • EDIT Blob

    • Chunk API: New Url
    • Chunk API: Binary data
    • Commit API:New Url