Welcome to the Pongr RESTful web services. This page provides both an overview of the API as well as entry points into it. The API currently has one primary purpose: you send it a picture and it sends you back information about an object recognized in that picture. It does several other things but that's the primary use case: recognizing objects in user-submitted pictures.
The API returns XHTML that is both displayable in a browser (although not very sexy) and parseable by a machine. So instead of reading boring documentation you can jump right in & use the API in your browser to see how it works. View the page source at any time to see the raw XHTML that your app can parse. We are also currently rolling out support for XML and JSON response formats.
But first, here are a few odds & ends you need to know about.
Every HTTP request to the API must include the following two parameters:
When using the API from your browser we take care of the app_name and app_user_id parameters for you, so you don't need to worry about them. We do this using an app_user_id cookie with your very own UUID (we're sneaky like that).
Let's face it: a lot of HTTP libraries (and browsers) out there are pretty lame and only support HTTP GET and POST. Our web services take advantage of PUT and DELETE, so what's a developer to do?
If you aren't able to make PUT or DELETE requests you can get around these limitations by making a POST request and doing one of two things:
As you explore the web service resources you'll probably notice a number of forms in the response representations. While it would be extremely cool if you wrote an artificially intelligent app that's smart enough to understand how to fill out & submit those forms, we really don't expect you to do that.
The purpose of those forms is just to make it clear to you, the human, how to make other requests to the web services, and to make it easy to do so using your browser.
Enough talk - let's make some HTTP requests and see some response representations! Here is a very concise overview of the various resources and supported HTTP methods.
Base URI: http://api.pongr.com/
| Resource | URI | Method | Description |
|---|---|---|---|
| Pictures | /pictures | GET | An example form for submitting a picture and a list of your recent pictures |
| Pictures | /pictures | POST | Uploads a picture and tries to recognize an object in it |
| Picture | /pictures/{id} | GET | Returns the representation of the specified picture |
| Picture | /pictures/{id}.jpg | GET | Returns the actual picture that was uploaded |
| Picture | /pictures/{id} | PUT | Updates the picture: used to describe/tag/share it and provide latitude/longitude |
The top-level pictures resource responds to a GET request with a list of pictures recently uploaded by the user identified by the app_name and app_user_id query parameters. The XHTML format also contains an example form that demonstrates how to upload a picture.
You create a new picture by sending it in a HTTP POST request to the top-level /pictures resource. The request must have the Content-Type:multipart/form-data header and contain the following parts:
If the upload was successful a 201 Created response is returned with the URI of the new picture resource in the Location header. The response body contains a representation of the new picture and its format is determined by the request's URI extension (ie .xhtml, .xml or .json) or Accept header.
The picture resource responds to a GET request with a representation of the picture in some format. The XHTML, XML and JSON formats contain various information about the picture, the object recognized in it, etc.
The JPEG format returns the actual uploaded picture, optionally resized using the following query parameters:
The request for the /pictures/{id}.jpg resource also supports the If-Modified-Since and If-None-Match headers and will return a 304 Not Modified response if the client can use a cached copy. Otherwise, the response will be a 200 OK with the picture in the body and the Last-Modified, ETag and Cache-Control headers to assist the client with caching the picture.
You update an existing picture by sending a HTTP PUT request to the /pictures/{id} resource. The request must have the Content-Type:application/x-www-form-urlencoded header and may contain any of the following parameters:
If the update was successful a 200 OK response is returned. The response body contains a representation of the updated picture and its format is determined by the request's URI extension (ie .xhtml, .xml or .json) or Accept header.
Got questions? Our Google Group has answers. The greatest minds on the planet are standing by, ready to help you out. And yes, that includes actual Pongr employees.
(coming soon!)
Oh, so you don't want to make raw HTTP requests and parse XHTML responses? No sweat, just use one of our SDKs. Available for your favorite programming language, they'll make it even easier to use our web services. Your boss will love how productive you are!
If you're a real REST geek and need a WADL file for our web services, here you go!
The Pongr RESTful web services were built using awesome technologies like Java, Scala, Jersey, Guice, JPA and StringTemplate. We were heavily inspired by the incredible RESTful Web Services book and of course Ruby on Rails.
