API v2
Design notes for version 2 of the Vote Smart A
PI.
Basic Interaction
URLs
URLs need to be simpler this time around. In the interest of simplicity, and easy to remember names, we'll use all-lowercase method names, that use HTTP verbs instead of verbs in the method call. All items will be plural. Any adjectives will be in HTTP GET variables and should be open to ALL root-level(at least) fields returned in the API.
The URL should also include the version number.
DECISION NEEDED: Should the default be to return all fields, or only a subset? Default would e most accessible, but some fields could be remarkably large and bandwidth intensive.
Returned fields(like cols in an SQL query) should be able to be specified.
DECISION NEEDED: Should returned content-type also be in the url as an extension? Or should that be in the request headers? Or either/or?!?
Examples:
api.votesmart.org/v2/candidates?candidate_id=9490&fields=candidate_id,firstname,lastname
api.votesmart.org/v2/candidates?elections.state_id=PA&elections.office_id=6
api.votesmart.org/v2/elections.candidates?election_id=1234&candidates.elections.party=*Democratic*
HTTP Headers
Lots of complexity can be hidden in the HTTP headers. Authentication(API Key(s)), content-type(see above for decision needed), caching, and other request-oriented(not data oriented) parameters.
DECISION NEEDED on these headers:
Content-Type ref
If-Modified-Since ref - If someone only wants to return(or check) recently updated items. We may want to also support HEAD requests in this case so people can easily check for updated content without returning everything.
Page - Page number to return
Amount - total records to return. I think default should be fairly high so that most requests this will be irrelevant.
Content-Type ref
If-Modified-Since ref - If someone only wants to return(or check) recently updated items. We may want to also support HEAD requests in this case so people can easily check for updated content without returning everything.
Page - Page number to return
Amount - total records to return. I think default should be fairly high so that most requests this will be irrelevant.
Authorization ref - Contains API key
Cache-Control ref - Whether or not or how the API software should pay attention to its cache
Overall HTTP header reference: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html
HTTP Response Codes
We should adhere as much as possible to standard HTTP response codes so developers can get an idea of what's going on(if they want to).
For instance:
200 OK
400 Bad Request
401 Unauthorized
404 Not Found
406 Not Acceptable (for bad input params)
413 Request Entity Too Large (for overly-broad requests)
503 Service Unavailable (if we turn the API off?)
Potential Tech
Frameworks
CherryPyquickview
More Information
API2ObjectsCategoryAPI2Planning
