What follows are a few best practices and tips that can help in the process and final product of your World Bank API application or library. Keep in mind this list is not exhaustive.

Caching

It's a good idea to implement a caching layer in your library or application that caches results of calls made to the API. There are a few main reasons to implement a caching layer. The first reason is the performance of your application. By caching API call results on your application side your application does not need to constantly go back and make a call to the API to get the same result over and over. A request made to the API is going to take longer than a request that's able to be served by a local cache. Related to performance is resource usage. If you cache API calls you'll generate less traffic back and forth to the API which can save bandwidth using for both the client as well as the API server.

Another reason to cache API calls in the client side is because not all requests to the API are fast. While there are several calls which the API can return very quickly, there are also slow calls. If you cache results the call will be slow only for the times where the local cache is not yet populated.

Finally, since the World Bank API is not guaranteed to always be up (though we try), if you have results cached locally then any disruption in service is less likely to be noticed. Above all, since results do not change very often - data is not added regularly like it would be with a daily news API or other very timely service - there's a lot to gain from caching your results. You can look at the WBAPI Drupal module as an example for how API result caching is implemented. You will see on its settings page it can cache API results for one day, two days, one week, two weeks, or even permanently.

Uptime

The World Bank API is not guaranteed to have 100% uptime. Although maximum uptime is a goal, as with any service disruptions can happen at any point along the networks and Internet between the client application and the API servers. It's important that your application be defensive and handle API downtime gracefully. One such way could be by implementing good caching, which in itself has benefits. Another strategy could be to aim for graceful failure if the API is not available.

Testing

When you build a client application or library for the World Bank API you'll likely need to do a lot of testing. One of the best tools to help with testing is simply your web browser. You can view API results directly in your web browser by entering the API calls as the web address. There are example calls on several of the API call overview pages, such as the Indicator Queries page. You can copy and paste the URLs in the examples section of these pages and view the API results directly in your browser.

XML results are usually easy to read directly in your web browser. However, JSON can be difficult as it usually renders as a plain text string with no formatting help for the human eye, and most often requires downloading and opening the file to see the results. At least one tool exists to aid with the legibility of JSON results in the web browser itself - a Firefox plugin called JSONView. This Firefox plugin adds line indentation, syntax highlighting, and the ability to view the JSON result directly in your web browser.

Other tips

  • Two response formats exist - XML and JSON. The JSON response is usually smaller in size than the XML response which is a good reason to consider using the JSON format if you have an option to prefer one format over the other in your application.

  • Not every call is fast. If you notice a certain call you make is slow you could search for alternatives. As a hypothetical example, if you need to query an indicator value for the last five years, check whether doing a year range query will be faster than making five separate queries, one for each year.

Help/Feedback

User Voice