Quantcast

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

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

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

curl -d answer=2 http://partners.sodahead.com/api/polls/1/vote/

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.