> For the complete documentation index, see [llms.txt](https://book.restfulnode.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://book.restfulnode.com/part-1/chapter-1/2-problem-1-structureless-design-structureless-rest.md).

# 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.](/files/SYFH1Muyw1jyI6SR0qFj)

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?


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://book.restfulnode.com/part-1/chapter-1/2-problem-1-structureless-design-structureless-rest.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.