Support

AddThis Web Service Framework

This document describes common properties of all web services available on http://api.addthis.com. This is separate from the AddThis Client API.



Requests

Requests are made via HTTP GET or POST as documented for each service. Most services will use URLs such as:

Version numbers in our URLs are associated with the service's API contract and will only increment when we're forced to make changes that are not backwards compatible. We regularly release updates and new features without incrementing the version number, similar to the "latest" versions that are offered by other services. New releases and versions will be posted in our blog and old URLs will generally remain available for a while after a new version is released.




Response Formats

Many services can return data in multiple formats such as json or xml. Pass your desired response format as a file extension at the end of the request URL (before the query string). For example:

http://api.addthis.com/call.json?param=value (json format)

Supported response formats are specified on a service-by-service basis. Available response formats include:

  • json
  • xml
  • csv
  • rss
  • html

When calling services that support html responses, you may omit the .html extension. Optionally, you can use json mode and pass callback=function to specify a jsonp callback wrapper. Content-Type headers are set on responses as appropriate.




HTTP Status Codes

HTTP status codes are set on all responses by default. Some clients (like flash) have trouble dealing with non-200 status codes on error responses. You can pass suppress_response_codes=true as an URL parameter to force a HTTP 200 status code on all responses, even when errors occur. If you suppress status codes, look for an error response to determine if an error occurred.




Pagination

Services that return long lists of data may paginate responses.

Paginated Request Parameters
Name Description Type Default
start # of results to skip before starting result set. integer 0
count maximum size of result set. integer service-specific
Paginated Response Elements
Name Description Type
start # of elements that were skipped before starting the response set. integer
count # of elements in the response. integer
total total number of elements. integer



Error Responses

Unsuccessful requests will return an HTTP status code pertaining to the error (unless suppressed) and standard error response in the format requested. An error response will always contain the "error" element with a specific (non-HTTP) error code, an error message and a detailed "info" object depending on the type of error. Here is a sample json error response:

{
   "error":{
      "code":30,
      "message":"invalid parameter",
      "info":{
         "invalidParameterName":"code",
         "invalidValue":"asdf"
      }
   }
}



Rate Limiting

Some services are rate limited by our servers to prevent abuse. Services may be limited by ip address, user account and other call parameters.




Authentication

We support two mechanisms for supplying authentication credentials to services which require them: URL parameters and HTTP Basic Authentication.

URL Parameters

In this mode, you supply your userid and password as URL parameters to your request. This is a very simple option when you're writing code to access our services.

Parameters:
Name Description
userid Your AddThis userid or email address.
password Your AddThis password.

These credentials will be used by the target service to validate your request. If you don't present credentials, or if your credentials aren't valid, the service will respond with an HTTP authentication challege (a 401 "Authorization Required" response).

Here is an example of a request URL which embeds authentication parameters:

http://api.addthis.com/analytics/1.0/pub/shares.json?userid=myuser&password=mypass

Keep in mind that your password will be transmitted in plain text across the network when making a call like this.

HTTP Basic Authentication

We support HTTP's Basic authentication scheme. When you request a service that requires authentication, you supply your credentials in a standard HTTP "Authorization" header.

The credentials you supply will be used by the target service to validate your request. If you don't present credentials, or if your credentials aren't valid, the service will respond with an HTTP authentication challege (a 401 "authentication failed" response).

Last Updated: Jul 10, 2013 02:00PM EDT
help@addthis.com
http://assets02.desk.com/
false
desk
Loading
seconds ago
a minute ago
minutes ago
an hour ago
hours ago
a day ago
days ago
about
false
Invalid characters found
/customer/en/portal/articles/autocomplete