Skip to content

The Wutup API

Jump to bottom
andyjwon edited this page Dec 2, 2012 · 16 revisions

Welcome Wutup Developers! You've found the API page.

Below you will find

  • A complete summary of each and every endpoint in the API
  • Usage notes describing the overall design philosophy and various common themes throughout the API
  • Tons of examples (most of you will probably just look at this section).

Webservice Endpoint Summary

The API supports the following endpoints:

Endpoint Query Parameters Description
GET /events page, pagesize, owner, name, categories Search for events
GET /events/:id — Get event details
POST /events — Create event
PATCH /events/:id — Update event details
DELETE /events/:id — Delete event
GET /geocode address Resolve given address to latitude/longitude coordinates. Replace spaces in the address with +'s.
GET /geocode lat, lng Resolve given latitude/longitude coordinates to a formatted address.
GET /occurrences page, pagesize, eventId, attendee, daterange, categories, venueId, center, radius Search for event occurrences
GET /occurrences/:id — Get occurrence details
POST /occurrences — Create an occurrence
PATCH /occurrences/:id — Update occurrence details
DELETE /occurrences/:id — Delete occurrence
GET /occurrences/:id/attendees page, pagesize Get users attending a specific occurrence
POST /occurrences/:id/attendees — Register as an attendee for an occurrence (body says which user)
DELETE /occurrences/:id/attendees/:userid — Unregister as an attendee
GET /venues page, pagesize, name, event, center, radius Search for venues
GET /venues/:id — Get venue details
POST /venues — Create a venue
PATCH /venues/:id — Update a venue
DELETE /venues/:id — Delete a venue
GET /venues/:vid/properties/ page, pagesize Get a venue's properties
POST /venues/:vid/properties/ — Add, update, and/or delete properties
GET /events/:id/comments page, pagesize Get comments for event
GET /occurrences/:id/comments page, pagesize Get comments for occurrence
GET /venues/:id/comments page, pagesize Get comments for venue
POST /events/:id/comments — Add new comment to event
POST /occurrences/:id/comments — Add new comment to occurrence
POST /venues/:id/comments — Add new comment to venue
PUT /events/:eid/comments/:cid — Update an event comment
PUT /occurrences/:oid/comments/:cid — Update an occurrence comment
PUT /venues/:vid/comments/:cid — Update a venue comment
DELETE /events/:eid/comments/:cid — Delete an event comment
DELETE /occurrences/:oid/comments/:cid — Delete an occurrence comment
DELETE /venues/:vid/comments/:cid — Delete a venue comment

Usage Notes

  • The media type for all request and response bodies, except for error responses, is application/json. Error responses use text/plain for application-level errors, or whatever media type the web server returns for errors that the service cannot detect itself. Clients need not pass in an accept header, although they should set a Content-type header on requests that have bodies.

  • The service uses HTTP methods as follows:

    GET collection ? query_parameters Returns all resources in a collection satisfying the query parameters. Default pagination values will be applied if none are supplied.
    GET _resource_ Retrieves full details of a resource.
    POST _collection_ Creates a new element within a collection. The request body must contain a specification of the resource to be created, _without the id field_. If the resource to be created is linked to existing resources, the JSON description in the request body should contain a specification of the linked resource with _only_ its id. A normal response is `HTTP 201 Created` with the `Location` header holding the URI of the newly created resource.
    PATCH _resource_ Updates (part of) a resource. The request body must contain a partial or full JSON specification of the object to be updated. If an id is present in the body, it must match the id in the URI. A normal response is `HTTP 204 No Content`.
    PUT _resource_ Replaces a resource. The request body contains a full JSON specification of the object to overwrite the existing resource. If an id is present in the body, it must match the id in the URI. A normal response is `HTTP 204 No Content`.
    DELETE _resource_ to delete a resource, given only its id. There should be no request body. A normal response is `HTTP 204 No Content`.
    • The following HTTP error response codes are detected by wutup:
      400 Bad Request Required parameters are missing, or parameters (such as integers or dates) are malformed.
      401 Unauthorized You've tried to access a resource that requires a login, but you aren't logged in.
      403 Forbidden The resource exists but you are not allowed to see it. For example, you've asked to see a page with 1000 results. The most you are allowed to access per request is 50.
      404 Not Found Everyone knows what this means.
      405 Method Not Allowed The client is trying to, for example, invoke a POST on an endpoint that only supports GET.
      406 Not Acceptable The client requested a media type that the server cannot satisfy, e.g., something that is not JSON for endpoints that return only JSON.
      409 Conflict You've specified conflicting information in a PUT, POST, or PATCH. For example, you may be trying to PUT an event with id 3 to the resource `/events/5`. You can avoid these problems by leaving ids out of the representations in your PUT and PATCH request bodies.
      415 Unsupported Media Type The request body is not JSON.

      • Geography searches are specified at the API level with a center and radius. The center is specified in lat,lon format (values in degrees) and the radius is in miles. The radius must be between 0 and 100 miles. Search regions that cross the poles or the 180° line of longitude will not be accurate.

      • Query parameters which are lists are specified in a comma-separated string, for example 1,5,8.

      • The specified "search circle" may be turned into a "box" to speed up searching. Given a center of longitude x and latitude y and radius r, we search for venues with latitudes in the range y-h to y+h and longitudes in the range x-h to x+h where:

      • h = r ÷ miles_in_a_degree_of_latitude_at_latitude_y

      • w = r ÷ miles_in_a_degree_of_longitude_at_latitude_y

      • Date ranges are specified with dates in ISO 8601 format (YYYY-MM-DD). They can be open or closed, and are always inclusive. For example:

        • 2012-12-30/2015-07-22
        • 2012-12-21/
        • /2013-01-02

      Examples

      Get events created by user 5, returning the first page of events, 10 per page.

      GET /events?owner=5&page=0&pageSize=10

      Get event 12.

      GET /events/12

      Create a new event. A JSON description of the event goes in the request body. Note the event id is NOT specified. Also, only the id of the creator is specified.

      POST /events
{
    "name":"Beach Party",
    "description":"Final exam",
    "creator":{"id":7}
}

      Update just the name of an event 4. The id, description, and creator, are not changed.

      PATCH /events/4
{
    "name": "Camping at Lake Sabrina"
}

      Update the name and creator of event 3. The description remains unchanged.

      PATCH /events/3
{
    "name":"GitHub Lecture",
    "creator":{"id":17}
}

      Delete event 7.

      DELETE /events/7

      Get all event occurrences for event 3, returning the first page with 15 per page.

      GET /occurrences?eventId=3&pageNumber=1&pageSize=15

      Get the 2nd page of occurrences within 10 miles of <35.22°N,116.7°W>, in venue 4, 20 per page.

      GET /occurrences?venueId=4&center=35.22,-116.7&radius=10&page=2&pageSize=20

      Get all event occurrences that occur between Thursday, 05 Jan 2012 12:00:00 GMT and Thursday, 31 May 2012 12:00:00 GMT, returning the default pagination for the application.

      GET /occurrences?start=1325764800000&end=1338465600000

      Create a new occurrence. A JSON description of the occurrence goes in the request body. Note the occurrence id is NOT specified. Also, only the id of venue and event are specified.

      POST /occurrences
{
    "event":{"id":1},
    "venue":{"id":1},
    "start":"2012-12-01T11:30:00",
    "end":"2012-12-01T12:00:00"
}

      Update the name and event of event occurrence 3. All other information remains unchanged.

      PATCH /occurrences/3
{
    "event":{"id":1}
}

      Find the first page of 10 venues hosting event 4 that are within 20 miles of <17°S,42.5°W>.

      GET /venues?event=4&radius=20&center=-17,-42.5&pageNumber=1&pageSize=10

      Retrieve venue 24.

      GET /venues/24

      Create a new venue. A JSON description of the venue goes in the request body. Note the venue id is NOT specified. In addition, we do not specify the venue properties here. They are created separately.

      POST /venues
{
    "name":"Pantages Theater",
    "address":"6233 Hollywood Boulevard  Los Angeles, CA 90028"
}

Clone this wiki locally