-
Notifications
You must be signed in to change notification settings - Fork 8
REST protocol v1
v1 of the REST protocol will have 3 resources: Spot, Spot search, and Spot image. All resources will require client application authentication, but unless otherwise stated will not require end user authentication. The method of authenticating client applications will be configurable, but the default and recommended authentication method will be OAuth 1.0a. All resources will have an etag, that must be validated for DELETE or PUT calls.
All representations are in JSON at this time, but clients should send an Accept header of application/json, as that may change.
URI: /api/v1/spot/<spot id>
Allowed methods: GET, PUT, DELETE
JSON Representation:
{
"id": "<spot id>",
"uri": "/api/v1/spot/<spot id>",
"name": "",
"type": ["study_room", "cafe"],
"location": {
"longitude": 0.00,
"latitude": 0.00,
"height_from_sea_level": 0.00,
"building_name": "",
"floor": 0,
"room_number": "",
"description": ""
},
"capacity": 0,
"display_access_restrictions": "",
"images": [
{
"id":"<image id>",
"url":"/api/v1/spot/<spot id>/image/<image id>",
"content-type":"image/...",
"width":0,
"height":0,
"creation_date":"Sun, 06 Nov 1994 08:49:37 GMT",
"modification_date":"Sun, 06 Nov 1994 08:49:37 GMT",
"upload_user":"user name",
"upload_application":"application name",
"thumbnail_root":"/api/v1/spot/<spot id>/image/<image id>/thumb",
"description": "Information about the image",
"display_index": 0
},
...
],
"available_hours":{
"monday": [ ["00:00", "10:00" ], ["11:00", "14:00"] ],
"tuesday": [ ["11:00", "14:00" ] ],
"wednesday": [ ["11:00", "14:00"] ],
"thursday": [ ["11:00", "14:00"] ],
"friday": [ ["11:00", "14:00"] ],
"saturday": [],
"sunday": [ ["11:00", "14:00"] ],
},
"organization": "",
"manager": "",
"extended_info": {
"whiteboards": true,
"field2": 0,
"field3": 0.00,
"field4": "",
},
"last_modified": "2012-07-13T05:00:00+00:00",
"items": [
{
"id": 796,
"name": "C-19074",
"category": "Digital Camera",
"subcategory": "",
"extended_info": {
"make_model": "Canon Powershot SD1100 IS",
"customer_type": "UW Student",
"auto_item_status": "active"
},
"images" : [
{
"id":"<image id>",
"url":"/api/v1/item/<item id>/image/<image id>",
"content-type":"image/...",
"creation_date":"Sun, 06 Nov 1994 08:49:37 GMT",
"upload_user":"user name",
"upload_application":"application name",
"thumbnail_root":"/api/v1/item/<item id>/image/<image id>/thumb",
"description": "Information about the image",
"display_index": 0
},
...
]
}
]
}
Extended info fields are defined by the institution. Manager holds the username of the person who created the Spot.
GET /api/v1/<spot id>
Accept: application/json
Response: 200, with a body of the JSON representation above.
This method requires end user authentication. In v1, all managers are trusted to manage all Spots.
PUT /api/v1/spot/<spot id>
Content-type: application/json
the body is the representation above.
Validation by default requires name, location.longitude, and location.latitude. This can be overridden by configuration, to require more fields, or add content restrictions.
On success, the response will be 200, with the new body as the content.
This method requires end user authentication. In v1, all managers are trusted to manage all Spots.
DELETE /api/v1/<spot id>
On success, the response will be 200.
To create a new Spot, POST to /api/v1/spot, with the body being the representation above.
POST /api/v1/spot
Content-type: application/json
... json representation ...
201 Created
Location /api/v1/<new spot id>
All fields are searchable.
- Nested fields are referenced with a : e.g. location:latitude.
- additional fields may be added:
- limit (Defaults to 20. No max if 0.)
- center_latitude
- center_longitude
- distance (Measured in meters)
- open_now (boolean / number)
- open_at / open_until (string in the form of ...)
- fuzzy_open_start / fuzzy_open_end (string in the form of ...)
- expand_radius (boolean)
- extended_info:or_group:<grouping value>=key will perform an 'OR' query across all keys with the same grouping value. The grouping value allows you to create multiple groups of keys to perform 'OR's within and 'AND's across the groups. This can only be done with keys that map to 'true' values.
- extended_info:app_type (uw_search only)
- search behavior is special on this field, if it is NOT passed in a search query param the only spots that will be returned are those that do not have the app_type extended_info
- if it IS passed in a search query, spots with that app_type will be returned.
To search based on items, use the following syntax: * item:name="item_name" * item:category="item_category" * item:subcategory="item_subcategory" * item:extened_info:"ei_key"="ei_value"
URI: /api/v1/spot/?
Allowed methods: GET
JSON Representation:
[
spot json representation,
...
]
GET /api/v1/spot/?center_latitude=47.653835¢er_longitude=-122.307809&distance=400&building_name=JHN
Accept: application/json
URI: /api/v1/spot/<spot id>/image
Allowed methods: POST
This accepts multipart form-data. The fields are image, description, and display_index. The display index must be zero or a positive integer.
URI: /api/v1/spot/<spot id>/image/<image id>
Allowed methods: GET, PUT, DELETE
Returns the image content
Deletes the image
Accepts multipart form-data. Same fields as a POST to /api/v1/spot//images
URI: /api/v1/spot/<spot id>/image/<image id>/thumb/<width>x<height>
Allowed method: GET
Returns a properly scaled version of the image. Returns a 404 if an invalid width or height is given.
URI : /api/v1/item/<item id>/image/<image id>
Returns a JPG, PNG, or GIF.
URI : /api/v1/item/<item id>/image/<image id>/thumb/<width>x<height>
Retrieves a thumbnail of the specified height. Returns a 404 if an invalid height or width is provided.
URI : /api/v1/item/<item id>/image/
This accepts multipart form-data. The fields are image, description, and display_index. Upon creation, a URL at which the created resource can be accessed will be returned.
URI : /api/v1/item/<item id>/image/<image id>
This method will require a trusted oauth key and an Oauth-User that is a spotseeker_server admin.
On success a 200 will be returned, if the user has insufficient privileges a 401 error will be returned.
URI: /api/v1/buildings
Allowed methods: GET
Returns a represntation of the buildings associated with all Spaces. Searches work the same as with a Spot search.
{
"Alder Hall",
"Allen Library (ALB)",
"Architecture Hall (ARC)",
"Burke Memorial-Washington State Museum (BMM)",
...
}
URI: /api/v1/schema
Allowed methods: GET
Returns a representation of all metadata allowed for a Space.
{
"id": "int",
"uri": "/api/v1/spot/<spot id>",
"name": "",
"type": ["study_room", "cafe"],
"longitude": "decimal",
"latitude": "decimal",
"height_from_sea_level": "decimal",
"building_name": "",
"floor": "unicode",
"room_number": "",
"description": ""
"capacity": "int",
"display_access_restrictions": "",
"images": [
{
"id":"<image id>",
"url":"/api/v1/spot/<spot id>/image/<image id>",
"content-type":"image/...",
"width":0,
"height":0,
"creation_date":"Sun, 06 Nov 1994 08:49:37 GMT",
"modification_date":"Sun, 06 Nov 1994 08:49:37 GMT",
"upload_user":"user name",
"upload_application":"application name",
"thumbnail_root":"/api/v1/spot/<spot id>/image/<image id>/thumb",
"description": "Information about the image"
},
...
],
"available_hours": "hours_string",
"organization": "",
"manager": "",
"extended_info": {
"has_whiteboards": "unicode",
"food_nearby": ['space', 'building', 'neighboring'],
"field3": "int",
"field4": "",
},
"last_modified": "2012-07-13T05:00:00+00:00"
}
URI: /api/v1/user/me/favorite/<spot id>
Allowed methods (Authenticated users only): GET, POST, DELETE
JSON Representation:
This returns true or false
URI: /api/v1/user/me/favorites/
Allowed methods (Authenticated users only): GET
JSON Representation:
[
spot json representation,
...
]