Best practices for working with the 7digital API
Use of the 7digital API has grown, and we are seeing a lot of innovative applications and websites using the API. We are constantly adding new things to the API, and doing a lot of work to improve it. This means that the will continue to change and if you don’t follow the guidelines below it is likely that your applications consuming the 7digital API may break.
We’ve seen a few API implementations that don’t use the API in an optimal and tolerant manner. This article is to give some guidance to build a resilient application around the API.
The motivation for this post also comes from a recent article on consuming web services http://martinfowler.com/bliki/TolerantReader.html.
Reading responses.
When reading the response, access elements by path and name, and use xpath if possible. Access elements by their hierarchy in the xml. Sometimes elements with the same name can appear in the same response under different parent elements. These can have different values depending on the parent element.
In your code that parses the xml, avoid accessing elements by index. For example as in elements[0] , instead access elements by name e.g elements[“name”] . If the order of xml elements change, your code will still work. The order of elements can and will change at any time. Please do not depend on elements being in a certain order in the API response.
The Schema.
We’ll make every effort not to break the schema, but you shouldn’t rely on this. Read the elements you need from the response. It’s best to write code that has a graceful fall back if a certain element is not populated or is missing. A missing element should not crash your application/website. The schema is not a binding contract, but a document which describes the structure of the response. In programming terms, treating the API response as a dynamic type, and not as a static type is recommended.
If you come across unexpected responses or discrepancies between documentation and the actual API behaviour don’t just work around these. Please get in touch and let us know about the problem and we’ll do our best to fix the issue or advise you on the right way to go.
OAuth.
The OAuth libraries at http://code.google.com/p/oauth/ are recommended. These are used in our code and there is a reference implementation in .Net with the OAuthconsole https://github.com/7digital/OAuthConsole
You should not need to do the 3-legged OAuth process each time you need to access an endpoint, that requires 3-legged OAuth. 3-Legged OAuth sets up a trust relationship between you (the consumer) and a 7digital user, who authorises you to make requests on their behalf. This should be setup only once. The access token and secret obtained during this process can be re-used till the 7digital user revokes access.
Local caching.
We return cache headers. Make use of it. Your application will be more responsive if you don’t make unnecessary server calls.
Placing a proxy server such as Squid between your application and the API, will give you caching quite easily and send requests to the server only when the cached item has expired.
Ask us
We are on twitter @7digitalapi and on google groups at 7digital API Developers. We are here to help you with your implementation. We’ve got sample code on the 7digital github page to help you get started.