API Style

Do you remember how many slices of bread you have eaten? In fact, bread also has another meaning, which is an acronym for browse, read, edit, add, and delete.

This chapter doesn’t have much knowledge, but mainly wants to discuss with you what the best style for writing BREAD in Milkio is. By the way, I will share with you the history of the popular REST.

REST and History

REST is a popular BREAD style, which is usually like this:

Name	HTTP Method	URL	HTTP Body
browse	GET	/user/	-
read	GET	/user/1	-
edit	PUT	/user/1	{ "name": "alice" }
add	POST	/user/	{ "name": "alice" }
delete	DELETE	/user/1	-

REST is a great style that emerged in the millennium and prevailed in the following decade.

In that era, the front end and back end were not as distinct as they are now. There were only RD and no FE or PE. The server dynamically changed the content by splicing HTML, without JavaScript or only used to add some interactive effects to the webpage, until Gmail used JavaScript to bring some small shocks to the world, and people realized the potential of JavaScript, which eventually evolved into a hurricane that swept the entire world.

The webpage content gradually no longer rendered by the server in advance, but dynamically obtained by XMLHttpRequest. The server increasingly became a provider of data in XML or JSON format to the front end, rather than HTML that mixed data with the interface.

Finally, dust to dust, earth to earth. Everything that users come into contact with is created by JavaScript running in the browser. The server only retains key parts such as providing data and ensuring security.

Problems with REST Now

Nowadays, clients have their own routing, usually implemented using history or location.hash. One reason why REST is no longer suitable is the complete separation of routing between the client and server.

The browser sends GET requests by default. The GET method is used to display pages, and other methods are used to perform actions. This is also why REST implements browse and read using the GET method.

Later, due to historical inertia, everyone still maintains the programming habits of REST, even if what is provided now is data instead of pages.

However, GET requests have an important problem: they have no request body. For REST, if you want to pass parameters to the server, you can only place them as part of the directory (for example, /user/1) or URL parameters (for example, /user/?id=1).

This limitation makes it impossible for us to pass complex parameters to the server, and the type information is lost in the process, unable to distinguish between numbers and booleans (because all parameters are truncated from the URL), and does not support arrays and objects.

One of the advantages of REST is to provide users with beautiful and intuitive URLs. But with the front end having its own routing function, users can no longer see the URL of our server. In addition, how many ways of passing parameters do we need to consider when writing APIs using REST?

Method	Example	Disadvantages
URL directory	/user/1	Can only pass single values, no types, and does not support arrays and objects
URL Params	/user/?id=1	No types, and does not support arrays and objects
Request Header	X-Foo-Bar	No types, and does not support arrays and objects
Request Body	{"name": "alice"}	None
Request Method	POST	Used to express the types of actions, which are one of GET, POST, PUT, DELETE

In addition, REST will also limit our API expression ability in many cases. When we want to implement user-related APIs, including registration, login, and BREAD operations, the intuitive URL should be like this:

/user/register
/user/login

In REST, if we strictly follow the specifications, we will face the dilemma of choosing the HTTP method for login and registration. If we still regard registration as addition and use the POST method, what about login? Moreover, if my management background needs to have a method for adding users, how to distinguish between addition and registration?

Which Style to Use

It’s time to adopt a new style that simplifies REST!

For this new style, first of all, all requests should use the POST method, so that parameter data can be passed entirely using the body.

And, in order to achieve type safety, JSON, a data format with types, should be used in the body instead of old data formats such as form-data/urlencoded.

Since there is no longer a distinction between methods, we can use the directory in the URL to represent resources, and the filename to describe actions to replace the responsibilities of methods.

/article/add
/article/delete
/article/comment/add
/article/comment/delete
...

As for the parameter part, all parameters are placed in the Request Body, and for Milkio, data sent in JSON format via the Body will be serialized as params in your code, and enjoy type safety. An actual request is as follows:

POST /article/add
Content-Type: application/json

{
  "title": "Hello world!",
  "content": "Welcome to example.com. This is your first post. Edit or delete it and start blogging!"
}

And in Milkio, you can easily receive it.

/src/apps/article/add.ts

export const api = defineApi({
  meta: {},
  async action(params: { title: string, content: string }) {
    // ...
  },
});

BREAD Template

When you learn to use Milkio and decide on other technology stacks to use, you may find it cumbersome to repeat writing BREAD code every time. With Milkio’s template function, you can make this project easy.