-
Notifications
You must be signed in to change notification settings - Fork 0
The Felina API is a Node.js-backed server that returns JSON responses to HTTP method calls.
Please note, the API spec is subject to breaking, backwards-incompatible changes until it reaches v1.0.0. It uses Semantic Versioning.
Semantic HTTP methods are used that correspond to the type of CRUD operation being performed:
| CRUD | HTTP |
|---|---|
| Create | POST |
| Read | GET |
| Update | PATCH |
| Delete | DELETE |
| Name | Type | Endpoint | Parameters | Response description |
|---|---|---|---|---|
| Login | POST |
/login |
String email, String pass
|
Login status |
| Register | POST |
/register |
String email, String name, String pass, String gravatar
|
Registration result |
| Job Start | POST |
/start |
Int[] imageIDs, Int exeID
|
Job ID |
| Job Progress | GET |
/progress |
Int jobID |
Job progress |
| Job Results | GET |
/results |
Int jobID |
Job results |
| Image Upload | POST |
/img |
Image[] images |
Image IDs |
| Executable Upload | POST |
/exec |
Executable, String name
|
Executable ID |
| Executable Retrieval | GET |
/exec |
Executable IDs, Names | |
| Image Serve | GET |
/img/:id |
:id - String id of an image |
Image file |
| Login Check | GET |
/logincheck |
Login status | |
| Facebook Login | GET |
/login/facebook |
??? | |
| Metadata Upload | POST |
/upload/metadata |
Object[] metadata |
Update result |
| Metadata Retrieval | GET |
/img/:id/meta |
:id |
Metadata object |
| Annotation Retrieval | GET |
/img/:id/anno |
:id |
Metadata object |
| Image Listing | GET |
/images |
Optional String uploader
|
Image array |
| Update User | PATCH |
/user |
Object user |
Success or Failure |
| [New Subuser] (#new-subuser) | POST |
/subuser |
String name, String email , Int projectid
|
Success or Failure |
| [Get Token] (#get-token) | GET |
/token |
String email |
String token |
| [Update Subuser] (#update-subuser) | POST |
/updatesub |
String email, String name, Int refresh
|
Success or Failure |
| [Get Subusers] (#get-subusers) | GET |
/subuser |
Object[] subuser array |
This method takes a string and plaintext password. The returned JSON will relay some basic user information or an error if login failed. Debugging: To check login status, GET /logincheck
This method registers a new locally authed user with the service. The name parameter will set the user's display name. After a succesfull registration, the user should be automatically logged in. Returned JSON will give either error status or the user information as registered on the server.
This method accepts a list of image IDs, and an executable ID. A new job is started by running the corresponding executable on the corresponding images. If any of the given IDs are invalid in any way, and error message will be returned and the job will not start. If all IDs are valid, the job starts and a unique job ID is returned.
Example request:
{
'executable': '4dafc690d01355d335169c52609bf08e',
'images': ['b3639a00751454b1fa0f0cc39fb5992c', '11d70a64fee30a8dacb58f7bdfcf25f3']
}If the request is successful, it returns a JSON object like this:
{
"res": true,
"code": 0,
"id": 1,
"images": [
"b3639a00751454b1fa0f0cc39fb5992c",
"11d70a64fee30a8dacb58f7bdfcf25f3"
],
"executable": "4dafc690d01355d335169c52609bf08e"
}If unsuccessful it returns:
{
"res": false,
"code": 2,
"id": null,
"msg": "Need to specify images and executable for a job"
}The ID is a globally unique ID that lasts the lifetime of the system. You can call methods 3 and 4 at any time with this ID to get information about the processing job that uses these images. Internally, it's generated by taking an MD5 hash of all the images and converting the hex string to a decimal number.
The status code is one of the following:
| Code | Meaning |
|---|---|
| 0 | Success -- no error |
| 1 | No images provided |
| 2 | No executable provided |
| 3 | One or more images are corrupt or in an invalid format |
| 4 | The executable is corrupt or in an invalid format |
| 3 | Internal error -- server failed to save the files |
| 4 | Unknown error |
This method accepts a job ID returned by method 2, and returns information about the current status of the processing operation, in the following format:
{
"status": {
"code": 0,
"message": "Request successful"
},
"progress": 0.73, // Progress percentage as a float between 0 and 1
"eta": 43829409, // Estimated time remaining in milliseconds
"processed": 43, // Number of images currently processed
"total": 92 // Total number of images in the job
}This method accepts a job ID returned by method 2. If the job has finished, it returns the textual data produced by the computer vision algorithm that was run on the uploaded images. If not, it returns an error.
Success
{
"status": {
"code": 0,
"message": "Request successful"
},
"data" {
// CV output data here
}
}Failure
{
"status": {
"code": 1,
"message": "Job not finished"
}
}This method accepts one or more binary image files in .jpg, .png or .bmp format and stores them on the server.
Upon success, a JSON object is returned in the following format:
{
"status": {
"code": 0,
"message": "Images uploaded successfully"
},
"ids": [1234, 5678, 9001] // Globally unique image ID numbers
}Upon failure, the following format is returned:
{
"status": {
"code": 2,
"message": "One or more images is corrupt or invalid"
}
}Where the error status code is one of the following:
| Code | Meaning |
|---|---|
| 0 | Success -- no error |
| 1 | No files provided |
| 2 | One or more provided images is corrupt or in an invalid format |
| 3 | Internal error -- server failed to save the files |
| 4 | Unknown error |
This method accepts a binary Windows computer vision executable and an associated name and stores it on the server. If successful:
{
"res": true,
"ids": [
"2e651dbb282cb231304811e110b4222d"
]
}If it already exists:
{
"res": false,
"err": {
"code": 2,
"msg": "Zip already exists: name"
}
}Returns an array of all executables uploaded by a user
This method will proxy an image from the storage backend to the client. The :id parameter, that forms part of the URL, is the 32 character alphanumeric id of the image to be served. If the image does not exist, or the user does not have permission to view the image, a placeholder will be displayed.
This method returns the current state of the user's login. This includes basic information such as email and display name.
This method redirects to the Facebook API, which in turn should redirect back to a callback on the server, taking you to the login status endpoint. WIP
This method takes a JSON array of metadata objects. Each object contains an array of image annotation objects. An example POST request body is as follows:
[
{
"id": "88f1991caaa149f4cd67393c30ea3d9d",
"datetime": "2014-02-14T03:39:13.000Z",
"location":
{
"lat": 54.5,
"lon": 0.4
},
"private": 1,
"annotations": [
{
"region": [
{ "x": 100, "y": 200 },
{ "x": 150, "y": 240 }
],
"tag": "I will be replaced soon, dont use me"
}
]
},
{
"id": "161aff2d85901edfefd668e0c94f1e7b",
"datetime": "2014-02-14T13:27:03.000Z",
"location":
{
"lat": -12.7,
"lon": -3.4
}
}
]This method will replace any existing metadata with the newly supplied values. Once annotation definitions are supported, these will also replace existing regions if present. Currently, annotations will be added to the current set.
This method will return a detail parameter, containing an array of information about the results of parsing and updating records. If an element of the response array is false, updating the database has failed due to an unspecified error. Otherwise, the element should reflect the result of parsing your request. Omissions from your request will be replaced with null values (or empty arrays). Any erroneous fields will be replaced with the value of false. In the event of errors with some inputs, other attributes will still be updated in the database.
An example response to the the above request is shown here:
{
"res": false,
"detail": [
{
"id": "88f1991caaa149f4cd67393c30ea3d9d",
"datetime": "2014-02-14T03:39:13.000Z",
"location": {
"lat": 54.5,
"lon": 0.4
},
"private": 1,
"annotations": [
{
"region": [
{
"x": 100,
"y": 200
},
{
"x": 150,
"y": 240
}
],
"tag": false
}
],
"priv": null
},
{
"id": "161aff2d85901edfefd668e0c94f1e7b",
"datetime": "2014-02-14T13:27:03.000Z",
"location": {
"lat": -12.7,
"lon": -3.4
},
"priv": null,
"annotations": []
},
false
]
}This method returns the basic metadata of a single image.
This method returns the annotations associated with a single image.
This method returns a list of images belonging to the current user. If uploader is set, it returns all the images belonging to the current user, uploaded by the uploader.
This updates the user.
If Bob wants to change his name and profile image he will send this.
{
"name": "Bob The Builder",
"profile_image": "this doesn't exist yet"
"email": "bob@gmail.com"
}If Bob is a researcher and he wants to elevate Barry to a researcher, he will send this.
{
"privilege": 2,
"email": "barry@gmail.com"
}This adds a new sub-user. (Requires 'researcher' privilege).
{
"name": "Bob"
"email": "$serial-key@example.com"
"projectid": "1"
}The email does not have to be a valid email address as it will not be verified. It merely has to be in valid email format. The $serial-key has be replaced with a UUID for each subuser. The client which provides the $serial-key will log in with this email and a token (in the password field) that will be sent to them on first connection. (see get token)
Provided the request is made within a valid time-frame, a token will be sent.
This updates the subuser. Requires the supervisor to be logged in.
{
"email": "subuser@example.com", //Required
"name": "new sub name", //Optional
"projectid": 1, //Optional
"refresh": 1 // to refresh the token or -1 invalidate the current token (Optional)
}Returns a response like
{
"res": true,
"subusers": [
{
"name": "sub1",
"email": "sub1@gmail.com",
"projectid": 1,
"invalidated": 0 // is not invalidated
},
{
"name": "subuser2",
"email": "sub2@gmail.com",
"projectid": 1,
"invalidated": 1 // is invalidated
},
{
"name": "sub3",
"email": "sub3@gmail.com",
"projectid": 1,
"invalidated": 1 // is invalidated
}
]
}