Problem #1: Structureless Design, Structureless REST

In the last decade or so, we can clearly see that REST has become so ubiquitous and common that many of the newer generations of developers have never even heard of other architectural styles like SOAP and XML-RPC. The term REST API has become synonymous with terms like HTTP and AJAX. In fact, there is a huge confusion when it comes to understanding the difference between REST and HTTP. We will explore more on this topic in the later chapters of this book.

Although many people create RESTful services and API endpoints, there are still no real formal guidelines and/or principles when it comes to designing them.

Even the first answer from google tells us that there are no "official" standards for building REST APIs.

This has become a huge issue because if there does not exist a set of standard guidelines, then everyone would do things a little bit differently. That is exactly how things have turned out in the past 10 - 15 years.

Take the simple act of designing a URI for a resource for example.

If we take a look at even some of the most popular tech companies like GitHub, Slack, and Twitter - you can see that even they kind of just wing it... They all have their own little way of building their own APIs.

Take one of GitHub's endpoints for example: https://api.github.com/repos/octocat/hello-world/code-scanning/alerts.

Notice the api in the subdomain and all of the letters in the URI are strictly lowercase.

https://docs.github.com/en/rest/reference/code-scanning

Now take a look at one of Slack's API endpoints: https://slack.com/api/chat.getPermalink.

The api is prefixed just after the top-level domain, it basically acts like a global namespace. What's more is that the chat.getPermalink almost let us wonder why they didn't just do something like /api/chat/permalink instead.

Could it be that internally Slack has a chat module and getPermalink is an action that's part of it?

https://api.slack.com/methods/chat.getPermalink

And then there's Twitter...

Take a look at this example: https://api.twitter.com/1.1/statuses/user_timeline.json.

Everything seems to be fine… until you realize they use underscores ( _ ) instead of hyphens ( - ).

Also, notice that you can specify the output response by adding a ".json" at the very end of the endpoint.

https://developer.twitter.com/en/docs/twitter-api/v1/tweets/timelines/api-reference/get-statuses-user_timeline

The question would then be, if there are no formal best practices and even the leading tech companies seem to be just winging it, then what set of guidelines can we follow when building our own APIs?