apiary.apib

FORMAT: 1A

# elasticthought

REST API wrapper for Caffe


# Group User
Related resources of the **User API**

## Users Collection [/users]

### Create a User [POST]
+ Request (application/json)

        { 
            "username": "foo",
            "email": "foo@foo.net",
            "password": "bar"
        }

+ Response 201 

    
# Group Data
Related resources of the **Data API**

## Datafiles Collection [/datafiles]

### Create a Datafile [POST]

The url passed in the JSON must point to a .tar.gz file.  That is currently the only format allowed.

+ Request (application/json)

    + Header

            Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

    + Body

            { 
                "url": "http://s3.com/mnist-data.tar.gz",
                "layers_type": "IMAGE_DATA"
            }
    + Schema 

            {
                "$schema":"http://json-schema.org/draft-04/schema#",
                "title":"Add Datafile Request",
                "description":"A request to create a new Datafile",
                "type":"object",
                "properties":{
                    "url":{
                        "description":"The url with the content of the datafile.",
                        "type":"string"
                    },
                    "layers_type":{
                        "description":"The format of the data (IMAGE_DATA or DATA).",
                        "type":"string"
                    },
                    "layers_data_param":{
                        "description":"The parameters associated with this data layer.",
                        "type":"object",
                        "properties":{
                            "backend":{
                                "type":"string",
                                "description":"The backend this DATA layer should use (LEVELDB or LMDB) - defaults to LEVELDB"
                            }
                        }
                    }
                },
                "required":[
                    "url",
                    "layers_type"
                ],
                "additionalProperties":false
            }
        

+ Response 201 (application/json)

        { "id": "datafile-uuid" }


## Datasets Collection [/datasets]

### Create a Dataset [POST]

If you want to split a single datafile, pass the same datafile id in both the training and the testing sections, and non-zero split percentages.

Otherwise if you've already split your data into two datafiles, specify different datafile id's, and give 0.0 for the split-percentages.

+ Request (application/json)

    + Header

            Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

    + Body

            { 
                "training": {
                    "datafile-id": "datafile-uuid", 
                    "split-percentage": 0.7
                },
                "testing": {
            "datafile-id": "datafile-uuid", 
                    "split-percentage": 0.3
                }
            }

    + Schema 

            {
                "$schema":"http://json-schema.org/draft-04/schema#",
                "title":"Add Dataset Request",
                "description":"A request to create a new Dataset from a Datafile or set of Datafiles",
                "type":"object",
                "properties":{
                    "training":{
                    "description":"The training portion of the dataset.",
                    "type":"object",
                    "properties":{
                        "datafile-id":{
                        "type":"string",
                        "description":"The id of the Datafile object"
                        },
                        "split-percentage":{
                        "type":"number",
                        "description":"The percent of datafile that should be used for training.  Or 0.0 if passing two distinct Datafile id's in training/testing"
                        }
                    }
                    },
                    "testing":{
                    "description":"The testing portion of the dataset.",
                    "type":"object",
                    "properties":{
                        "datafile-id":{
                        "type":"string",
                        "description":"The id of the Datafile object"
                        },
                        "split-percentage":{
                        "type":"number",
                        "description":"The percent of datafile that should be used for training.  Or 0.0 if passing two distinct Datafile id's in training/testing"
                        }
                    }
                    }
                },
                "required":[
                    "training",
                    "testing"
                ],
                "additionalProperties":false
            }


+ Response 201 (application/json)

        { 
            "_id": "dataset-uuid"
            "datafile-id": "datafile-uuid",
            "processing-state": "pending",
            "training": {
                "split-percentage": 0.7
            },
            "testing": {
                "split-percentage": 0.3
            }
        }
        
        
# Group Training
Related resources of the **Training API**

## Solvers Collection [/solvers]

### Create a Solver [POST]
+ Request (application/json)

    + Header

            Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

    + Body

            { 
                "dataset-id": "<dataset-id>",
                "specification-url": "http://s3.com/mnist_solver.prototxt",
                "specification-net-url": "http://s3.com/mnist_train_test.prototxt"
            }

+ Response 201 (application/json)

        { "id": "solver-uuid" }
        
## Training Jobs Collection [/training-jobs]

After a solver is defined, create a training job that will use the solver to train a model.

### Create a Training Job [POST]
+ Request (application/json)

    + Header

            Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

    + Body

            { 
                "solver-id": "solver-uuid"
            }

+ Response 201 (application/json)

        { 
            "id": "training-job-uuid",
            "processing-state": "pending"
        }
        
## Training Job Status [/training-jobs/{id}/status]

The status of the Training Job 

+ Parameters
    + id (required, string, `training-job-uuid`) ... The id of the training job.

### Training Job Status [GET]
+ Request
 
    + Headers
 
            Authorization: Token 527d11fe429f3426cb8dbeba183a0d80

+ Response 200 (application/json)

        { 
            "id": "training-job-uuid",
            "state": "running",
            "loss": 0.0013,
            "last-iteration": 2000,
            "max-iterations": 10000,
            "logs": "/training-jobs/{training-job-uuid}/logs"
        }

## Training Job Logs [/training-jobs/{id}/logs]

The logs of the Training Job.  Currently returns entire text file, but in the future 
it will support websocket streaming.

+ Parameters
    + id (required, string, `training-job-uuid`) ... The id of the training job.

### Training Job Logs [GET]
+ Request
 
    + Headers
 
            Authorization: Token 527d11fe429f3426cb8dbeba183a0d80

+ Response 200 (text/plain)


# Group Prediction
Related resources of the **Prediction API**

## Classifiers Collection [/classifiers]

### Create a Classifier [POST]

+ Request (application/json)

    + Header

            Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

    + Body

            { 
                "specification-url": "http://s3.com/mnist_classifier.prototxt",
                "training-job-id": "<training-job-id>",
		"scale": "255",
		"image-width": "28",
		"image-height": "28",
		"color": false,
		"gpu": false
            }

+ Response 201 (application/json)

        { "id": "classifier-uuid" }

## Classify an input [/classifiers/{id}/classify]

Classify an input image

+ Parameters
    + id (required, string, `classifier-uuid`) ... The id of the classifier

### Classify [POST]


+ Request (multipart/form-data; boundary=---BOUNDARY)

    + Header

            Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

    + Body

            -----BOUNDARY
            Content-Disposition: form-data; name="urls"
            http://s3.com/imageurl1.png
            -----BOUNDARY
        
            -----BOUNDARY
            Content-Disposition: form-data; name="urls"
            http://s3.com/imageurl2.png
            -----BOUNDARY
        
            -----BOUNDARY
            Content-Disposition: form-data; name="files"; filename="imagefile1.png"
            Content-Type: application/octet-stream
            <raw file data>
            -----BOUNDARY
        
            -----BOUNDARY
            Content-Disposition: form-data; name="files"; filename="imagefile2.png"
            Content-Type: application/octet-stream
            <raw file data>
            -----BOUNDARY

+ Response 201 (application/json)

        { 
            "id": "classification-job-uuid",
            "processing-state": "pending"
        }