Anatomy of a request URL

APIs are the lifeblood of the internet. They provide accessible and secure data layers for many purposes. I love APIs, but they are also a tough nut to crack. If, like me, you have looked for economies of scale in API integration, you will have realised that the landscape is vast and lacking standardisation.

Each API is somehow different from the other, making each API integration unique. This is especially true when we look at the request urls of APIs. Each API request URL looks different, and this almost always causes us to create adhoc code to handle the little quirks of each individual API. After all, they are unique.

Except they are not.

When observed from an abstract point of view, all APIs can be broken down in basic components that can make API integrations simpler and more modular.

Let’s look at a series of complex request URLs, all supporting GET method.

Parts of a URL

API urls are made of a combination of

Base_url/Endpoint/Explicit path parameters/Implicit path parameters/ Appended Endpoint?Query Parameter

Endpoints:

Endpoints are identified solely by their position. Their meaning though is not consistent, sometimes they indicate the data space, sometimes the version.

Parameters:

• When divided by / are called ‘path’ parameters, but sometimes they are explicitly stating a key ‘country’, and a value ‘USA’, sometime they are implicit, /CA/
• When preceded by ? are called ‘query’ parameters, and they are always stating a key ‘country’ and a value ‘USA’ with = in between

Appended Endpoints:

Then there are appended endpoints, that again are only identifiable by their position, and not by their meaning. You find them at the end of the path parameters, but preceding the query parameters.

Conclusion

APIs are all different, but in a way they are all the same. By implementing this taxonomy, it’s possible to generalise them and set up a data structure that can simplify most of the code design. Try it out, let me know what you think of it.