As Stefan Tilkov notes tearfully, the REST API for the World Bank data leaves something to be desired. The URI to fetch the list of countries looks like this:
In my review of the Leonard Richardson and Sam Ruby book RESTful Web Services I summarized their best practices for making a service “look like the web”:
- Data are organized as sets of resources
- Resources are addressable
- An application presents a broad surface area of addressable resources
- Representations of resources are densely interconnected
So in this case, the resource that is the list of countries might simply be modeled as:
Likewise, given that the indentifier for electric power consumption is EG.USE.ELEC.KH.PC, and for China is CHN, you might have:
Or, for all countries:
Or, to fetch all indicators for China:
If the data were organized this way, and if results included URIs for traversing up and down, you could explore this web of data by just navigating around in it.
When you draw attention to this question of style, you risk seeming like a pedantic REST philosopher. But it’s really just a practical, down-to-earth kind of thing. If I’m a developer exploring a collection of data, it’s convenient to be able to navigate a web of linked resources, and have the API revealed to me as I go along.