======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 [[http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.17 ref]]
If-Modified-Since [[http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.25 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 [[http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.8 ref]] - Contains API key
Cache-Control [[http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.9 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===
CherryPy
[[https://bitbucket.org/weholt/django-quickview/src/fde97a0a0befaeda0ab2317035f8e7cd9c311511/docs/basic.md?at=default quickview]]

====More Information====
[[API2Objects]]

----
CategoryAPI2Planning