Today we’re delighted to announce the public launch of API v2 beta. We’ve rebuilt the whole API from the ground up, taking into account all of the experience, experimentation and feedback we gained from the first version. The result is a high quality API which is even more powerful than its predecessor.
Fresh documentation
We believe the most important part of an API is its documentation. We’ve created a shiny new documentation site for both the latest beta version and the original API v1. One of the best things about this new documentation is the live examples, where you can enter your API key, select one of your sites, and play around with all of the API functions and parameters using real data for your site. Besides this, the documentation is generally much cleaner and more descriptive.
Fully RESTful
API v2 follows RESTful design principles, offering a rich HTTP query model supporting HTTP POST/GET/PUT/DELETE methods invoking CREATE/READ/UPDATE/DELETE resource operations.
Response formats
The default response format is JSON. The API can also respond with JSONP if given the ‘callback’ query string parameter, and CSV for supported functions (e.g. timeSeries).
Logical response data
We’ve changed the default response structure of JSON data to be more representative of its actual content. For examples, when you request the pages function to obtain a list of currently active content, you get back an array of objects, one for each page. Additionally, in contrast to API v1, the response data is no longer nested in a property.
Presenters
Occasionally you might want the response data to be structured differently for convenience in your app. Some functions have presenters which can adapt the structure of the response data. For example, a plain GET request to the referrers function will send back an array list of unique referring URLs, but if you also supply the &presenter=groupByDomain query string parameter, the function will respond with a list of objects that in turn contain a list of referring URLs from a common domain.
If you desire a particular response structure but the API function doesn’t yet support it, get in touch with your idea and we can implement it.
Combining functions
Multiple functions can be combined into a single HTTP request, so that the response contains data from each function grouped into a single response. Each function’s data is keyed by the function name.
Grouping the response data in this way helps cut down on the number of HTTP requests your app needs to perform, saving on bandwidth and cumulative load time, which is particularly important on mobile devices.
Error handling for humans
API v1 was a little hostile when it came to errors. It got embarrassed when it encountered an issue and didn’t offer you much insight into what happened or how to rectify the problem.
The new API is much more approachable in an error situation. If something goes wrong, you’ll get a non-200 HTTP response status code. The code will give you an idea of whose fault the problem was. You’ll get a 4xx error if you did something wrong, or a 5xx error if the API is to blame.
Further to this, the data in the body of an error response will contain an additional error code, along with a message. You can look up the code using the error code reference, or there may be more information about the error code on the function’s documentation page. For a 4xx error, the error message tries to be as descriptive as possible to help you identify where you went wrong when making the request.
If any component function of a combination request encounters an error, its response data will contain information about the error, without affecting any of the other functions.
Stability and versioning
For the duration of an API version being in an alpha or beta stage, it will be labelled with the version ‘latest’. At time of writing, API v2 is in beta, and is therefore the current ‘latest’ version. When the latest version reaches a mature state, it will be locked down to patches only and released with a v<number> label.
Individual functions also have their own stability status. This allows us to release cutting-edge functionality to developers as soon as we craft it.
We will be maintaining API v1 for some time longer, but it will eventually be deprecated. We will endeavour to give plenty of notice before this happens. Nonetheless, we strongly encourage developers to build on API v2 and above.
The API is for you
We’ve lovingly put all of this together for you. Therefore, what you think is of huge importance to us. Having problems? Something you love? Something you hate? You have to let us know. You’ll be helping make the experience as great as possible for all, and we always take your feedback into account.
