CloudFactory Platform API
(This is the v4 version of the Platform API. The documentation for the v3 version of the API is available here)
The CloudFactory Platform API allows you to programmatically send work into and receive results from a production line in the Platform.
Overview
Version
This is the fourth version of the API. The version is indicated in the requests by passing v4 as a parameter in the endpoint.
Schema
All API access is over HTTPS and the root endpoint is:
https://api.cloudfactory.com
All data is sent and received as JSON.
$ curl -i https://api.cloudfactory.com/v4/lines
HTTP/1.1 200 OK
Server: nginx
Date: Fri, 12 Oct 2012 23:33:14 GMT
Content-Type: application/json; charset=utf-8
Connection: keep-alive
Status: 200 OK
[
{
"name": "Receipt Digitization",
"id": "5ve51anpY3"
},
{
"name": "PaperText",
"id": "WQAMSdIJb2"
},
{
"name": "Image Digitization",
"id": "7Bgu1iHm2k"
}
]
All timestamps are returned in ISO 8601 format.
YYYY-MM-DDTHH:MM:SSZ
Authentication
All API requests are authenticated using HTTP Basic Authentication. The username and password can be found in your Setting page in the Platform.
Most HTTP libraries allow username and password to be supplied directly in the URL. Thus, your request should be posted to:
https://username:password@api.cloudfactory.com
Errors
All API requests need authentication. All requests without correct credentials will return 401 Unauthorized.
HTTP/1.1 401 Unauthorized
{
"message": "Bad credentials"
}
If the request endpoint is invalid or the requested resource does not exist, 404 Not Found is returned. The same status is returned when authentication credentials are missing or the authenticated user is not authorized to access the requested resource.
HTTP/1.1 404 Not Found
{
"message": "Not found"
}
If you have general access to the resource but are not authorized to perform a specific operation, 403 Forbidden is returned.
HTTP/1.1 403 Forbidden
Forbidden
The request body(payload) needs to be valid JSON. If it's not, 400 Bad Request is returned.
HTTP/1.1 400 Bad Request
{
"message": "Problem parsing the body"
}
When a required field (key) is missing from the request, 422 Unprocessable Entity is returned.
HTTP/1.1 422 Unprocessable Entity
{
"message": "Invalid request. \"<key>\" is missing in the request."
}
When the value of a certain field is of an incorrect type, 422 Unprocessable Entity is returned.
HTTP/1.1 422 Unprocessable Entity
{
"message": "Invalid request. <value> is not a string."
}
List Production Lines
This lists all the production line associated with your user account.
GET /v4/lines
Response
Status: 200 OK
[
{
"name": "Receipt Digitization",
"id": "5ve51anpY3"
},
{
"name": "PaperText",
"id": "WQAMSdIJb2"
},
{
"name": "Image Digitization",
"id": "7Bgu1iHm2k"
}
]
Create a Production Run
A Production Run is a batch of units that are sent at a time to the Platform for processing. A run should contain at least one unit in it but can contain more as well.
You can create a production run in the Platform with following request:
POST /v4/runs
Input
| Name | Type | Description |
|---|---|---|
line_id |
string | Required. The unique identifier of the production line. You can find it in your production line setting page. |
callback_url |
string | The URL to which the results are posted after the units are processed in the Platform. If the URL requires HTTP Basic authentication, the username and password can also be supplied in it. |
units |
array | Required. An array of objects. Each object contains an input for a unit as a collection of key-value pairs. The values can themselves be an object. It is recommended to have a key named identifier as part of the input to uniquely identify the unit. The input is returned with the result. |
Input Example
{
"line_id": "M4tCqxaL5tYou",
"callback_url": "https://username:password@api.yourdomain.com/v2/result",
"units": [
{
"identifier": "0000001",
"image_url": "http://yourdomain.com/assets/image_0000001.png",
"company": "Microsoft"
},
{
"identifier": "0000002",
"image_url": "http://yourdomain.com/assets/image_0000002.png",
"company": "Google"
}
]
}
Response
| Name | Type | Description |
|---|---|---|
id |
string | The unique identifier for the production run that has been created. You might want to save this value in your system so that you could fetch the production run result later. |
line_id |
string | The unique identifier of the production line. |
status |
string | The status of the units posted. The value is Processing indicating that the units in the production run are being processed. |
created_at |
string | The time when the run was created. |
Response Example
Status: 201 Created
{
"id": "E7gVrtVQJx",
"line_id": "M4tCqxaL5tYou",
"status": "Processing",
"created_at": "2015-09-03T09:18:38Z"
}
Get a single Production Run
Once all the units in a production run have been processed in the Platform, they are posted back to the callback URL provided in the original request. However, you can also send a request to the Platform to proactively fetch the result.
GET /v4/runs/:id
Input
The input is provided as a parameter in the path segment.
| Name | Type | Description |
|---|---|---|
id |
string | The unique identifier of the run for which the result is to be fetched. |
Response
| Name | Type | Description |
|---|---|---|
id |
string | The unique identifier of the production run. |
line_id |
string | The unique identifier of the production line. |
created_at |
string | The time the units were sent into the Platform. |
processed_at |
string | The time all the units were finished processing and the result was posted back. |
status |
string | The status of the production run. If the run has finished processing, the value is Processed. If the run isn't yet processed completely, the value is Processing . Please note that this status is for the entire run. In order to find the status of individual unit, refer to the status of specific unit inside units. |
units |
array | An array of objects. Each object contains the result for a unit. Refer to the next table to view the structure of this object. |
The result object for each unit contains:
| Name | Type | Description |
|---|---|---|
input |
object | The original input you sent for the input. |
output |
object | The output generated by the Platform for the unit. |
meta |
object | Other important data about the unit. |
meta.status |
string | The status of the unit. The possible values are Processing, Completed, Flagged, and Aborted. Status Processing means that the unit is still being processed. Status Completed signifies that the unit was successfully completed. Status Flagged indicates that the unit could not be completed for some reason. Aborted indicates that the unit was aborted before it could be processed. |
meta.created_at |
string | The time when the unit got created in the Platform. Usually, this time is same as the time the production run got created. |
meta.processed_at |
string | The time when the unit got processed in the Platform. Individual units are often processed earlier than the overall run. |
Response Example
Status: 200 OK
{
"id": "E7gVrtVQJx",
"line_id": "M4tCqxaL5tYou",
"created_at": "2015-09-03T09:18:38Z",
"processed_at": "2015-09-03T09:39:21Z",
"status": "Processed",
"units": [
{
"input": {
"identifier": "0000001",
"image_url": "http://yourdomain.com/assets/image_0000001.png"
},
"output":{
"company": "Microsoft",
"location": "USA"
},
"meta":{
"status": "Completed",
"created_at": "2015-09-03T09:18:38Z",
"processed_at": "2015-09-03T09:25:28Z"
}
},
{
"input":{
"identifier": "0000002",
"image_url": "http://yourdomain.com/assets/image_0000002.png"
},
"output":{},
"meta":{
"status": "Flagged",
"created_at": "2015-09-03T09:18:38Z",
"processed_at": "2015-09-03T09:27:28Z"
}
}
]
}
The schema of the response posted to the callback_url is also exactly the same. However, the request is posted only after all units in a run are processed.
Abort a Production Run
When a production run is created, the Platform starts processing it by breaking down the units into smaller tasks and distributing them to workers.
If you decide that you don't want the units of a particular run to be processed, you may request to abort it. The abort operation tries to stop the remaining tasks from going to workers. Even though the Platform does its best to abort the run, the operation doesn't always succeed especially if a unit is already close to being processed. Therefore, all, some, or none of the units in the run may end up being aborted depending on how far they have progressed in the production line.
You can send the abort request by:
POST /v4/runs/:id/abort
Input
| Name | Type | Description |
|---|---|---|
id |
string | The id of the production run that needs to be aborted. |
Input Example
POST /v4/runs/n7Fjfx1sZ4/abort
Response
The abort operation is performed asynchronously. Therefore, the Platform will respond by 202 Accepted.
{
"message": "The request has been accepted and is in progress"
}
In order to find the status of the units in the run, you need to check the run directly. If the status of the run is Processing, the operation is still in progress. If the status is Processed, it means that the operation is complete. However, you'll need to check the status of specific units in the run to find if it was aborted or not.
For example, you can check the status of the run with id n7Fjfx1sZ4 after sending 'abort' request by:
GET v4/runs/n7Fjfx1sZ4
The response would look something like this.
Status: 200 OK
{
"id": "n7Fjfx1sZ4",
"line_id": "eWlMZKN8uY",
"created_at": "2015-12-15T08:41:31Z",
"processed_at": "2015-12-15T09:15:27Z",
"status": "Processed",
"units": [
{
"input": {
"image_url": "https://s3.amazonaws.com/receipts.cf.com/w_0001.jpg",
"identifier": 1
},
"output": {
"store_name": "Seven Crossings",
"amount": "6.50"
},
"meta": {
"status": "Completed",
"created_at": "2015-12-15T08:41:33Z",
"processed_at": "2015-12-15T08:43:33Z"
}
},
{
"input": {
"image_url": "https://s3.amazonaws.com/receipts.cf.com/w_0002.jpg",
"identifier": 2
},
"output": {},
"meta": {
"status": "Flagged",
"created_at": "2015-12-15T08:41:33Z",
"processed_at": "2015-12-15T09:15:27Z"
}
},
{
"input": {
"image_url": "https://s3.amazonaws.com/receipts.cf.com/w_0003.jpg",
"identifier": 3
},
"output": {},
"meta": {
"status": "Aborted",
"created_at": "2015-12-15T08:41:33Z",
"processed_at": "2015-12-15T09:15:27Z"
}
}
]
}
The status of the run is Processed which means that processing is over. The run has three units. Looking at `meta.status' of individual units, it is evident that only one unit was aborted successfully. The rest were either completed or flagged.
Note that the output field of the unit is empty if it is aborted just like when it is flagged.
If the run was already processed when you send the 'abort' request, you'll receive 405 Method Not Allowed.
{
"message": "The run is already processed and cannot be aborted"
}