This is a followup from my previous post, in which I critiqued the simple Synonyms Service available on the Azure Datamarket.
To repeat, the existing URI structure for the service is like this:
GET https://api.datamarket.azure.com/Bing/Synonyms/GetSynonyms?Query=%27idiotic%27
How would I do things differently?
The hostname is just fine – there’s nothing wrong with that. So let’s focus on the URI path and the other parts.
GET /Bing/Synonyms/GetSynonyms?Query=%27idiotic%27
Here’s what I would do differently.
- Simplify. The URI structure should be simpler. Eliminate Bing and GetSynonyms from the URI path, as they are completely extraneous. Simplify the query parameter. Eliminate the url-encoded quotes when they are not necessary. Result: GET /Synonyms?w=improved
- Add some allowance for versioning. GET /v1/Synonyms?w=positive
- Allow the caller to specify the API Key in the URI. (Eliminate the distorted use of HTTP Basic Auth to pass this information). GET /v1/Synonyms?w=easy&key=0011EEBB4477
What this gets you, as an API provider:
- This approach allows users to try the API from a browser or console without registering. The service could allow 3 requests per minute, or up to 30 requests per day, for keyless access. Allowing low-cost or no-cost exploration is critical for adoption.
- The query is as simple as necessary and no simpler. There is no extraneous Bing or GetSynonyms or anything else. It’s very clear from the URI structure what is being requested. It’s “real” REST.
What about multi-word queries? Easy: just URL-encode the space.
GET /v1/Synonyms?w=Jennifer%20Lopez&key=0011EEBB4477
There’s no need to add in url-encoded quotes for every query, in order to satisfy the 20% case where the query involves more than one word. In fact I don’t think multi-word would even be 20%. Maybe more like 5%.
For extra credit, do a basic content negotiation that looks at the incoming Accepts header and modifies the format of the result based on that header. As an alternative, you could include a suffix in the URI path, to indicate the desired output data format, as Twitter and the other big guys do it:
GET /v1/Synonyms.xml?w=adaptive&key=0011EEBB4477
GET /v1/Synonyms.json?w=adaptive&key=0011EEBB4477
As an API provider, conforming to a “pragmatic REST” approach means you will deliver an API that is immediately familiar to developers regardless of the platform they use to submit requests. That means you have a better chance to establish a relationship with those developers, and a better chance to deepen that relationship.
That’s why it’s so important to get the basic things right.