API Help

Welcome to the OnSAP API. Currently this API is limited to read-only access to OnSAP.

API Usage

The OnSAP API is accessed via HTTP on the API URL (the URL of the page you're looking at right now). The method you want to access is then appended to the URL. For example to use the get_user method you would open a connection to the following URL:

http://www.onsap.com/api/1.0/users/username

The format of the data returned can be one of the following:

• json application/json
• xml application/xml
• debug text/html

The format is selected based on the Accept HTTP header or can be provided as URL parameter:

http://www.onsap.com/api/1.0/badges/?format=xml

The language of the response is selected from the Accept-Language header or the lang URL parameter:

http://www.onsap.com/api/1.0/badges/?lang=de

It is strongly recommended to use the HTTP headers instead of the URL parameters. The headers allow you to provide multiple values and let the server pick the ones that are available.

For debugging you can use your web browser and open the URL with it. The default headers of a web browser will return the response in debug HTML format which shows you the data right in your browser in a human readable fashion.

General Rules

The API follows REST semantics as closely as possible without causing too much troubles for server and client. Make sure to follow the following rules:

• If a resource URL is documented with a trailing slash you must connect to it with a trailing slash
• For valid requests the server will never return a redirect you have to handle.
• All data returned, except for data that is HTML, is not preprocessed. If you intend to embedd it on a webpage make sure to properly escape the data!
• Rendered HTML is only valid in HTML 4 and HTML 5, not in any version of XHTML! If you are using XHTML and want to embedd rendered data you must parse it as HTML and dump into XML.
• The encoding used for requests and responses to and from OnSAP are always utf-8.
• The API responds with HTTP error codes. Make sure to be able to handle every error code the RFC specifies.

XML Format

If you don't want (or can) use the JSON format which is strongly recommended you can also use our XML representation of the data.

The following rules apply for the XML format:

• All elements returned from the API belong to the http://opensource.plurk.com/solace/ XML namespace.

• If an object in JSON has a #type key and the value starts with onsap. the value after onsap. is used as tag:

  {'#type': 'onsap.foo', 'bar': 'bar'}

  becomes in XML

  <foo><bar>baz</bar></foo>

• Otherwise the object is returned as dict and the type is stored as attribute:

  {'foo': 'bar', '#type': 'special'}

  becomes in XML

  <dict type="special"><foo>bar</foo></dict>

  If no #type key exists that attribute is missing.

• List items are wrapped in a list tag:

  [1, 2, {'foo': 'bar'}]

  becomes in XML

  <list><item>1</item><item>2</item><dict><foo>bar</foo></dict></list>

Methods

The following API methods exist:

• List Badges

  Returns a list of all badges. Each badge in the returned list has the same format as returned by the "get badge" method.

  URL

  /api/1.0/badges/

  Allowed methods

  GET

• Get Badge

  Returns a single badge.

  URL

  /api/1.0/badges/<identifier>

  Allowed methods

  GET

• Ping

  Helper function to simpliy test the API. Answers with the same value. Once API limitations are in place this method will continue to be "free" and as such suitable for connection checking.

  URL

  /api/1.0/ping/<int:value>

  Allowed methods

  GET

• List Questions

  Lists all questions or all questions in a section.

  URL

  /api/1.0/questions/

  Allowed methods

  GET

• Get Question

  Returns a single question and the replies.

  URL

  /api/1.0/questions/<int:question_id>

  Allowed methods

  GET

• Get Reply

  Returns a single reply.

  URL

  /api/1.0/replies/<int:reply_id>

  Allowed methods

  GET

• List Users

  Returns a list of users. You can retrieve up to 50 users at once. Each user has the same format as a call to "get user".

  Parameters

  • limit — the number of items to load at once. Defaults to 10, maximum allowed number is 50.
  • offset — the offset of the returned list. Defaults to 0

  URL

  /api/1.0/users/

  Allowed methods

  GET

• Get User

  Looks up a user by username or user id and returns it. If the user is looked up by id, a plus symbol has to be prefixed to the ID.

  URL

  /api/1.0/users/+<int:user_id>

  Allowed methods

  GET

• Get User

  Looks up a user by username or user id and returns it. If the user is looked up by id, a plus symbol has to be prefixed to the ID.

  URL

  /api/1.0/users/<username>

  Allowed methods

  GET