Web API
Introduction
This document defines the end points, request and response definitions of CloudyRec backend web service Version 0.1 application interface. The required information such as app key, resource keys can be found under Sandbox or Production sections of your developer dashboard. Record IDs can be find through the data browser.
Security
- Developer shall keep the App Key and Resource Key secret at all time.
- Every HTTP request must contains the Secret Key as header “secret-key” or as HTTP params “secret-key”. (NOTE: http is not impleted yet.)
- Server checks the validity of App Key, Resource Key and Secret Key combination.
- Server accepts all HTTP request on SSL connection. (NOTE: http is not implemented yet)
Sandbox vs Production
Sandbox API
- Sandbox API is opened once the App is locked from Dashboard using the Resource and Attribute definition defined.
- Sandbox API is closed once the App is unlocked from Dashboard to edit the definition.
- Sandbox API runs on a set of low end silo servers, thus performance is lower than production servers.
- Sandbox end point shall not be used for production clients.
- Based on the fair usage policy, Sandbox API of misusing App will be unloaded from Sandbox servers.
- Analytics for Sandbox is not available in Dashboard.
Sandbox Endpoint
- The Sandbox API server address is different from Production API server address.
- The end point may be different from time to time, and decided at the time of locking and loading.
- Developer shall edit the end point value in the source code by copying it from Dashboard Sandbox tab.
- Version number for sandbox endpoints is ‘0’.
Production Instance API
- Production API is opened once the App is published from Sandbox state.
- Only the Apps locked into Sandbox can be loaded to Production state.
- All request to Production API are chargable.
- App definition loaded for Production API is frozen and cannot be changed anymore.
- Re-publishing of App with same name from Sandbox will produce new Production instace with new version number.
- Analytics are collected for every Production instance and available from Dashboard.
- Production instances run on a set of high performance server clusters with fully redundent and scalable cloud configuration.
Production Endpoint
- Production instance end point is generated at the time of publishing.
- Developer shall edit the end point value in the source by copying it from Dashboard Production tab.
Data Exchange Format
- Primary data exchange format used by API is JSON.
- Server returns array of JSON objects with attributes defined by developer.
- Server returns error message in JSON format in case of error, along with HTTP error code.
Error Response
- Server returns error as HTTP error code with error message in JSON format as follow:
{message" : "custom error message}
- Client shall check the response HTTP code first before reading the JSON response.
- Server returns error message even in case of internal server error with code 500.
Create New Resource
- Client will send HTTP POST request to following url:
http://[end_point]/:version/:app_key/:resource_key
- The resource data can be posted as HTTP parameters using attribute names as keys.
- The resource data can also be posted as JSON hash assigned to HTTP parameter name ‘d’.
Response
- Upon successful creation, server returns as String representing newly created Resource ID with HTTP response code 201.
Authenticate a Resource
- This is only applicable to Authenticable Resource.
- Client will send HTTP POST request to following url:
http://[end_point]/:version/:app_key/:resource_key/auth
- The request must contain “_uname” and “_passwd” as HTTP POST parameters.
Response
- Upon successful authentication, server returns authenticated object data in JSON format with HTTP response code 200.
- If request is called for unauthenticable resource, error message is return with HTTP response cod 403.
Edit Existing Resource
- Client will send HTTP PUT request to following url:
http://[end_point]/:version/:app_key/:resource_key/:resource_id
- The resource data can be posted as HTTP parameters using attribute names as keys.
- The resource data can also be posted as JSON hash assigned to HTTP paramter name ‘d’.
- The data may include all attributes or only attributes of updated data.
Response
- Upon successful update, server returns as String representing updated Resource ID with HTTP response code 200.
Delete Existing Resource
- Client will send HTTP DELETE request to following url:
http://[end_point]/:version/:app_key/:resource_key/:resource_id
Response
- Upon successful delete, server returns empty response with HTTP response code 204.
List Existing Resources
- Client shall send HTTP GET request to following url:
http://[end_point]/:version/:app_key/:resource_key/
Pagination Parameters
- l = limit, number of records to retrieve per page.
- p = page number, the current number of the page to display.
Please note that p number starts at 1.
*Example:
http://[end_point]/:version/:app_key/:resource_key?l=1&p=1
Related Resources
Let’s say we have 2 resources called ‘user’ and ‘post’. And ‘post’ belongs to ‘user’. So if you want to retrieve all the posts belong to a particular user, the resource key will be the key for ‘post’ and ‘master_id’ will the id of that particular user.
Create New Related Resource
- Client will send HTTP POST request to following url:
http://[end_point]/:version/:app_key/:resource_key
- The resource data must contain _master_id as a parameter while sending this request.
Listing Related Resource
- Client shall send HTTP GET request to following url:
http://[end_point]/:version/:app_key/:resource_key/cof/:master_id
Uploading new file to Fstore
- Client shall post HTTP multipart request with data to following URL
http://[end_point]/:version/:app_key/fstore
- File data must be set with param name “file”.
- File size must not exceed 1 mega byte.
Response
- Upon successful creation, server returns as String representing updated Resource ID with HTTP response code 201.
Listing Fstore records
- Client shall send HTTP GET request to following URL
http://[end_point]/:version/:app_key/fstore/list
Response
- Server returns array of fstore objects in JSON format.
- Each fstore object contains following fields
- “id” FStore object id.
- “file_name” File name object Fstore object when it is uploaded.
- “tags” Comma separated value of tags.
Pagination Parameters
- l = limit, number of records to retrieve per page.
- p = page number, the current number of the page to display.
Downloading file from Fstore
- Client shall send HTTP GET request to following URL
http://[end_point]/:version/:app_key/fstore/:resource_id
- “resource_id” is the Id of fstore object.
Response
- Server will send stored data as attachment with HTTP response code 200.
Deleting file from Fstore
- Client shall send HTTP DELETE request to following URL
http://[end_point]/:version/:app_key/fstore/:resource_id
- “resource_id” is the Id of fstore object to be deleted.
Response
- Upon successful deletion, server will send empty resonse with response code 204.
Setting tags for Fstore file
- Client shall send HTTP PUT request to following URL
http://[end_point]/:version/:app_key/fstore/:resource_id/tags - with parameter name “tags” with tag values as comma separated string.
Response
- Upon successful update, server will send “resource_id” of updated record.
Getting tags for Fstore file
- Client shall send HTTP GET request to following URL
http://[end_point]/:version/:app_key/fstore/:resource_id/tags
Response
- For valid resource_id, server will response tags data in following JSON format
{"tags":“tag1,tag2,tag3”}
Common Error Responses
- 401 — {"message":“Unauthorized.”}
- 403 — {"message":“Not allowed.”}
- 406 — {"message":“[custom message]”}
- 408 — {"message":“Operation timeout.”}
- 500 — {"message":“[custom message]”}
Date Types
CloudyRec allows following data types for attributes;
- String
- Unique String
- Encrypted String (not for selection)
- Integer
- Decimal
- DateTime
- Boolean
Special note for Encrypted String
- This is a special String data type which is stored encrypted on the server.
- PUT or POST a new value for attribute of Encrypted String is encrypted by server upon receiving the request using unique salt, specific to Resource.
- GET to attribute of Encrypted String is NOT decrypted in respose and it cannot be decrypted, since it is one way hash.
- This is specially used for storing _password attribute of authenticable resources.
Special note for Unique String
- This is a special String data type which does not allow duplication in storage.
- API response error if duplicate is found upon POST and PUT of attribute value.
- This is used for storing _uname attribute of authenticable resources.
URL Listing
| #EP | Method | URL | Description |
| EP01 | N.A | N.A | Reserved |
| EP02 | GET | /:version/:app_key/count | Get total record count for for all resources of given app. |
| EP03 | GET | /:version/:app_key/:resource_key/count | Get total record count for given app and resource keys. |
| EP04 | GET | /:version/:app_key/:resource_key | Get resource list for given app and resource keys. |
| EP05 | GET | /:version/:app_key/:resource_key/cof/:master_id | Get related resource list,from given app key, of the type of given resource keys, which has given master_id. |
| EP06 | GET | /:version/:app_key/:resource_key/:resource_id | Get details attributes and values, from given app key, of the type of given resource keys, of given resource id. |
| EP07 | POST | /:version/:app_key/:resource_key | Create a new resource of given app and resource keys. |
| EP08 | POST | /:version/:app_key/:resource_key/auth | Authenticate a resource of given app and resource keys. |
| EP09 | PUT | /:version/:app_key/:resource_key/:resource_id | Update a resource with given attribute. |
| EP10 | DELETE | /:version/:app_key/:resource_key/:resource_id | Delete a resource with given resource_id. |