SodaHead.com REST API

URI

http://partners.sodahead.com/api/<service>/

• service: Path to the service.

Supported Formats

JSON -- we aren't about holy wars; we have developers using both vim and emacs. JSON is simply our preferred transport, as it is fast, concise, and ubiquitous.

Optional GET Parameters

• jsonp: Callback function to wrap JSON-formatted responses

  function-pattern must match "^[\w_.]+$"

  http://partners.sodahead.com/api/<service>/?jsonp=<namespace.function_name>

• limit: Limit the number of items returned (default: 10; max: 40)

  http://partners.sodahead.com/api/<service>/?limit=<limit>

• ext: Extensions (comma separated)

  geo

  http://partners.sodahead.com/api/<service>/?ext=geo

Error Codes

• 400 Error: Bad Request: You omitted a required parameter or SodaHead couldn't make sense of a parameter you supplied.

  {"error": "error_code"}

  • version_rejected

    You requested an API version not supported. API versioning is not present in URIs unless otherwise specified; otherwise, we do our best to continue backwards compatability or will provide a versioning to be supported for ~6 months.

  • format_rejected

    You requested a response format not supported. At this time, we only support JSON, and while one can specify a format in URIs, it is an optional parameter and left out of URIs.

  • jsonp_rejected

    You requested a jsonp pattern not supported.

  • api_limit_rejected

    You requested an unsupported paging limit.

• 404 Error: Not Found: SodaHead couldn't make sense of the URI supplied.

  {"error": "not_found"}

• 500 Error: Internal Error: An internal error within SodaHead occured. Please let us know if this error persists -- though we've likely have already been alerted.

  {"error": "server_error"}

Get multiple polls.

URI

GET http://partners.sodahead.com/api/polls/

GET http://partners.sodahead.com/api/polls/author/<author_id>/

GET http://partners.sodahead.com/api/polls/topic/<topic-label>/

• author_id: The numerical ID of the desired author

  topic-label: The topic label of the desired topic (ex. michael-jackson)

Example Request / Response

http://partners.sodahead.com/api/polls/

http://partners.sodahead.com/api/polls/author/2/

http://partners.sodahead.com/api/polls/topic/michael-jackson/

Error Codes

• 400 Error: Bad Request: You omitted a required parameter or SodaHead couldn't make sense of a parameter you supplied.

  {"error": "error_code"}

  • author_id_rejected

    You requested an unavailable author's polls.

  • topic_rejected

    You requested an unavailable topic or topic-label is malformed.

    topic-label must match "^\w+(-\w+)*$"

Get a single poll, specified by the poll_id parameter below.

URI

GET http://partners.sodahead.com/api/polls/<poll_id>/

• poll_id: The numerical ID of the desired poll

Example Request / Response

Error Codes

• 400 Error: Bad Request: You omitted a required parameter or SodaHead couldn't make sense of a parameter you supplied.

  {"error": "error_code"}

  • poll_id_rejected

    You requested an unavailable poll.

Cast a vote, specified by poll_id and answer (id) below.

URI

POST http://partners.sodahead.com/api/polls/<poll_id>/vote/

• poll_id: The numerical ID of the desired poll

• answer (id): The numerical ID of the desired answer

Example Request / Response

Error Codes

• 400 Error: Bad Request: You omitted a required parameter or SodaHead couldn't make sense of a parameter you supplied.

  {"error": "error_code"}

  • answer_absent

    Your request is missing an answer.

  • poll_id_rejected

    You requested an unavailable question.

  • answer_rejected

    You requested an unavailable answer.

  • request_refused

    The answer provided is invalid. Most likely, you are requesting a vote to be cast without having viewed the associated question during this session.