Important

This document is a proposal.

Resources

To get a good overview of what REST api means, consider reading Web Api Design, Crafting interface that Developers love.

• Users is the collection of registered users.
• Reports is a collection of geolocalized reports submitted by users.
• Photos is a collection of geolocalized photos.

Principles

• The standard format for input is application/x-www-form-urlencoded and multipart/form-data. See W3C recommendation for more info.
• The standard format for output is JSON.
• A successful POST (used to create a new resource) will return HTTP 201 (created). The newly-created resource’s URL is contained in the “Location” header of the HTTP response.
• A successful PUT (used to change an existing resource or create a resource which URL is known before creation) will return HTTP 200 (OK).
• A PUT call may not make any changes to a resource that would change its URL.
• Attempting to call a method on a type that doesn’t support it regardless of authentication (e.g. PUT or POST on read-only resources) will raise HTTP error 405 (method not supported).
• Attempting to call a method on a resource that doesn’t exist will raise HTTP error 404 (not found).
• Likewise, attempting to create a resource with a reference to something that doesn’t exist will raise HTTP 404.
• Missing, or incorrectly-formatted, parameters (e.g. letters in numeric parameters, negative quantities where disallowed) will raise HTTP 400 (bad request).

Note

Unless specified, all parameters are required and cannot be empty.

Users

To be done

Reports

GET /reports?location=longitude,latitude&radius=radius&offset=offset&limit=limit

Returns a paginated list of reports. If no parameter is provided, reports in antechronological order (newests first).

Optionnal query parameters:

location:The longitude/latitude around which to retrieve information. This must be specified as longitude,latitude. radius:Defines the distance in meters within which to return results. Default to 50. offset:Numbers of records to skip. Default to 0. limit:Maximum number of reports returned (default to 20).

Response format example for /reports?location=-73.583885,45.522706&limit=2&offset=2:

{
   "reports":
      [
         {
            "report":
               {
                  "_id": "5183bef9e2a9c30005648611",
                  "author": "devon",
                  "description": "Water all over the street.",
                  "created": "2013-03-28T09:15:12+00:00",
                  "location":
                     {
                        "type": "Point",
                        "coordinates": [73.59432, 45.5233]
                     },
                  "tags": ["accident", "water"],
                  "report_photos":
                     {
                        "photos":
                           [
                              {
                                 "photo":
                                    {
                                       "_id": "5118fe5ab821d90005c1a24d",
                                       "author": "devon",
                                       "location":
                                          {
                                             "type": "Point",
                                             "coordinates": [-73.583885, 45.522706]
                                          }
                                    },
                                 "links":
                                    {
                                       "self": "http://api.velobstacles.com/photo/5118fe5ab821d90005c1a24d",
                                       "report": "http://api.velobstacles.com/report/5183bef9e2a9c30005648611",
                                       "author": "http://api.velobstacles.com/users/519f7c699978d00472bab9e7",
                                       "thumbnail": "http://cdn.velobstacles.com/d64c1cefeda4dadf695d3edd47ef1d85",
                                       "original_resolution": "http://cdn.velobstacles.com/3d5e2f6f37c8ab46ec7cb3a29bfb0bca",
                                       "low_resolution": "http://cdn.velobstacles.com/8cb4f88ffd80dac9c59859dcea8e2ae4"
                                    }
                              }
                           ],
                        "links":
                           {
                              "self": "http://api.velobstacles.com/reports/5183bef9e2a9c30005648611/photos",
                              "report": "http://api.velobstacles.com/reports/5183bef9e2a9c30005648611"
                           }
                     }
               },
            "links":
               {
                  "self": "http://api.velobstacles.com/reports/5183bef9e2a9c30005648611",
                  "photos": "http://api.velobstacles.com/reports/5183bef9e2a9c30005648611/photos",
                  "author": "http://api.velobstacles.com/users/519f7c699978d00472bab9e7"
               }
         },
         {
            "report":
               {
                  "_id": "5183c05ee2a9c30005648624",
                  "author": "rob_ford",
                  "description": "Big crack on road",
                  "created": "2013-03-28T09:15:12+00:00",
                  "location":
                     {
                        "type": "Point",
                        "coordinates": [73.5856, 45.5233]
                     },
                  "tags": ["working site"],
                  "report_photos": null
               },
            "links":
               {
                  "self": "http://api.velobstacles.com/reports/5183c05ee2a9c30005648624"
               }
         }
      ],
   "links":
      {
         "self": "http://api.velobstacles.com/reports?location=-73.583885,45.522706&radius=50&offset=2&limit=2",
         "previous": "http://api.velobstacles.com/reports?location=-73.583885,45.522706&radius=50&offset=0&limit=2",
         "next": "http://api.velobstacles.com/reports?location=-73.583885,45.522706&radius=50&offset=4&limit=2",
         "first": "http://api.velobstacles.com/reports?location=-73.583885,45.522706&radius=50&offset=0&limit=2",
         "last": "http://api.velobstacles.com/reports?location=-73.583885,45.522706&radius=50&offset=6&limit=2"
      }
}

GET /reports/_id

Returns a report.

Response format example:

{
   "report":
      {
         "_id": "5183bef9e2a9c30005648611",
         "author": "devon",
         "description": "Water all over the street.",
         "created": "2013-03-28T09:15:12+00:00",
         "location":
            {
               "type": "Point",
               "coordinates": [73.59432, 45.5233]
            },
         "tags": ["accident", "water"],
         "report_photos":
            {
               "photos":
                  [
                     {
                        "photo":
                           {
                              "_id": "5118fe5ab821d90005c1a24d",
                              "author": "devon",
                              "location":
                                 {
                                    "type": "Point",
                                    "coordinates": [-73.583885, 45.522706]
                                 }
                           },
                        "links":
                           {
                              "self": "http://api.velobstacles.com/photo/5118fe5ab821d90005c1a24d",
                              "report": "http://api.velobstacles.com/report/5183bef9e2a9c30005648611",
                              "author": "http://api.velobstacles.com/users/519f7c699978d00472bab9e7",
                              "thumbnail": "http://cdn.velobstacles.com/d64c1cefeda4dadf695d3edd47ef1d85",
                              "original_resolution": "http://cdn.velobstacles.com/3d5e2f6f37c8ab46ec7cb3a29bfb0bca",
                              "low_resolution": "http://cdn.velobstacles.com/8cb4f88ffd80dac9c59859dcea8e2ae4"
                           }
                     }
                  ],
               "links":
                  {
                     "self": "http://api.velobstacles.com/reports/5183bef9e2a9c30005648611/photos",
                     "report": "http://api.velobstacles.com/reports/5183bef9e2a9c30005648611"
                  }
            }
      },
   "links":
      {
         "self": "http://api.velobstacles.com/reports/5183bef9e2a9c30005648611",
         "photos": "http://api.velobstacles.com/reports/5183bef9e2a9c30005648611/photos",
         "author": "http://api.velobstacles.com/users/519f7c699978d00472bab9e7"
      }
}

POST /reports

Submit a report.

Required parameters:

author:Author’s username description: longitude: latitude: tags:A list of tags.

HTTP response header example:

HTTP/1.1 201 Created
Connection: keep-alive
Content-Length: 116
Content-Type: application/json; charset=UTF-8
Date: Tue, 21 May 2013 16:25:29 GMT
Location: http://api.velobstacles.com/reports/5183bef9e2a9c30005648611

Response format example:

{
   "report":
      {
         "_id": "5183bef9e2a9c30005648611",
         "author": "devon",
         "description": "Water all over the street.",
         "created": "2013-03-28T09:15:12+00:00",
         "location":
            {
               "type": "Point",
               "coordinates": [73.59432, 45.5233]
            },
         "tags": ["accident", "water"]
      },
   "links":
      {
         "self": "http://api.velobstacles.com/reports/5183bef9e2a9c30005648611",
         "photos": "http://api.velobstacles.com/reports/5183bef9e2a9c30005648611/photos",
         "author": "http://api.velobstacles.com/users/519f7c699978d00472bab9e7"
      }
}

DELETE /reports/_id

Delete a report.

Photos

GET /photos?offset=offset&limit=limit

Get photo list.

Optionnal query parameters:

radius:Defines the distance in meters within which to return results. Default to 50. offset:Numbers of photo to skip. limit:Maximum number of photos returned (default to 20).

Response format example for /photos?offset=4&limit=2:

{
   "photos":
      [
         {
            "photo":
               {
                  "_id": "5118fe5ab821d90005c1a24d",
                  "author": "devon",
                  "location":
                     {
                        "type": "Point",
                        "coordinates": [-73.583885, 45.522706]
                     }
               },
            "links":
               {
                  "self": "http://api.velobstacles.com/photo/5118fe5ab821d90005c1a24d",
                  "report": "http://api.velobstacles.com/report/5183bef9e2a9c30005648611",
                  "author": "http://api.velobstacles.com/users/519f7c699978d00472bab9e7",
                  "thumbnail": "http://cdn.velobstacles.com/d64c1cefeda4dadf695d3edd47ef1d85",
                  "original_resolution": "http://cdn.velobstacles.com/3d5e2f6f37c8ab46ec7cb3a29bfb0bca",
                  "low_resolution": "http://cdn.velobstacles.com/8cb4f88ffd80dac9c59859dcea8e2ae4"
               }
         },
         {
            "photo":
               {
                  "_id": "51367fa288a8be000596e2a1",
                  "location":
                     {
                        "type": "Point",
                        "coordinates": [-73.583885, 45.522706]
                     }
               },
            "links":
               {
                  "self": "http://api.velobstacles.com/photo/51367fa288a8be000596e2a1",
                  "report": "http://api.velobstacles.com/report/5183bef9e2a9c30005648611",
                  "thumbnail": "http://cdn.velobstacles.com/0da8c9479b837745ef625f875c3f0e1b",
                  "original_resolution": "http://cdn.velobstacles.com/a598b26963ec7f531aaabdd447f60c02",
                  "low_resolution": "http://cdn.velobstacles.com/8cb4f88ffd80dac9c59859dcea8e2ae4"
               }
         }

      ],
   "links":
   {
      "self": "http://api.velobstacles.com/media?offset=4&limit=2",
      "previous": "http://api.velobstacles.com/media?offset=2&limit=2",
      "next": "http://api.velobstacles.com/media?offset=6&limit=2",
      "first": "http://api.velobstacles.com/media?offset=0&limit=2",
      "last": "http://api.velobstacles.com/media?offset=10&limit=2"
   }
}