# Problem #1: Structureless Design, Structureless REST

In the last decade or so, we can clearly see that [REST](https://en.wikipedia.org/wiki/Representational_state_transfer) 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.](https://3677909196-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MYnZ9vtSknI-QgfJcQ4%2Fuploads%2Fgit-blob-f246a2a550bb7ecffcf949cf12ad6092af1471bd%2Fguidelines-google-answer.png?alt=media)

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](https://en.wikipedia.org/wiki/Uniform_Resource_Identifier) 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](https://lh3.googleusercontent.com/_5Aqt-86QgDAPv0C1oHlJN8NQnRUcdXnZE2lC8QWekxtRy4lZj93vOi5p8g6lqzzkCY3mF_-6VYvp_plFS1aV7ZkljIHtwZsoG8s_5GRZE_tntDEZNct4hdN1yfCAJjwkYu8Rf_Q)

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](https://lh3.googleusercontent.com/kvzuMRyDZdSjkA1LJ2tdOe8o2T6M0chn_Bk6Wg9HwZkv60-bXn_7O3ujmM1K3D1C1McpT3bTY2sk68om0x52XxxpZF2HfrwriwVqVkSos1MWutBnH-WU9NVsVw_8KfgXcTCvpL_t)

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](https://lh6.googleusercontent.com/CilJ0ER1cfrrF9E1rDm2UMpSNnIXbf47iBmzuXUUTXWbmYWzbHaihGCwNe9vFs3prqXWH-W25NORfUt1QK0VXJ5NLJYnBK7uS_85j1I8pW2nRk9faFlqcsl1GUJKbxoFwePOcXOh)

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?