HTTP: A REST-ful API

How it works?

Go to ccv/serve. This functionality requires support of libdispatch and libev. Luckily, these libraries are easy to install, for example, on Ubuntu 12.04 LTS, you can simply:

sudo apt-get install libdispatch-dev libev-dev

and it is done. If you are on Mac OSX, you can simply:

brew install libev

and it is done.

On Mac OSX, you have to manually remove -ldispatch in ccv/serve/makefile, other than that, you are one ‘make’ away:

cd serve/ && make && ./ccv

Now, it is up and running!

How can I use it?

Following chapters assumed that you have basic understanding of curl.

The HTTP API as it is now, only supports 5 major ccv functionalities: BBF, DPM, SWT, TLD and SIFT. All these APIs are discoverable, you can simply:

curl localhost:3350

and it will return you the list of API endpoints that you can navigate, try one:

curl localhost:3350/dpm/detect.objects

It returns:

{
   "request":{
      "interval":"integer",
      "min_neighbors":"integer",
      "model":"string",
      "source":"blob",
      "threshold":"number"
   },
   "response":[
      {
         "x":"integer",
         "y":"integer",
         "width":"integer",
         "height":"integer",
         "confidence":"number",
         "parts":[
            {
               "x":"integer",
               "y":"integer",
               "width":"integer",
               "height":"integer",
               "confidence":"number"
            }
         ]
      }
   ]
}

All responses from ccv are JSON encoded, like the example above. Particularly, the above JSON encodes what a POST request should look like, and what kind of JSON data structure you can expect as return. From the description, we knew that we should encode file into source field, and specify what model you want to use:

curl -F source=@"pedestrian.png" -F model="pedestrian" localhost:3350/dpm/detect.objects

The above query should give you a series of detected rectangles that denotes pedestrians in the given image.

ccv supports multipart-encoded parameter, as well as query strings, the above query is equivalent to:

curl -F source=@"pedestrian.png" "localhost:3350/dpm/detect.objects?model=pedestrian"

Or:

curl --data-binary @"pedestrian.png" "localhost:3350/dpm/detect.objects?model=pedestrian"

Any ‘source’ parameters in ccv HTTP API can be passed directly as HTTP body.

A more advanced example would be TLD. Read more.

Under the hood?

On Life-cycle of a Request

Whenever you issued a HTTP request, ccv received such request with libev, in asynchronous fashion, and then dispatch a processing function to another thread with libdispatch, when the data is ready, ccv will dispatch back to main event loop and send result back. Thus, requests to ccv won’t block each other. Although silly, dummy GET requests to ccv HTTP API endpoints can easily peak to around 25K requests per second, you shouldn’t worry too much about its HTTP performance (you should more worry about its computer vision algorithms’ performance).

On Error Message

ccv’s HTTP endpoints doesn’t provide informative error messages, if you issued a request that it cannot handle, will return 400 with ‘false’ in its body. It may not be a problem for most of the API endpoints, but it would be for some advanced ones.

On Parameters

All HTTP API’s parameters can be easily interpreted through the C API documentation, ccv chooses reasonable defaults from start, so any of them are optional.

On Security

The HTTP API endpoints are not intended to be exposed to public Internet, you should hide these behind firewalls.

HTTP: A REST-ful API

How it works?

How can I use it?

Under the hood?

‹ back