RESTful API: we do everything wrong
Hi, Habr! Before I start, it's worth talking a little about yourself. I have been engaged in serious development not so long ago (three years in all), and it seems to me that it is the lack of years of experience that often allows me to look at many traditions and well-established ways of performing standard tasks from an original point of view. My specialty is the backend of sites and mobile applications (the main development language is python3, my favorite framework is Django).
Immediately I warn you that this article is not an example of implementation, there is no code here at all. It is rather a reflection on the topic of REST, aggregating sources known to me, so that those who also face my problem do not have to search for a long time for a guide to action.
The reason for writing this article was a dispute with my colleague about the naming of REST entities: he argued that it was necessary to call them in the plural, for example,
')
All anything, but the same discussion was repeated a month later with another colleague who opened the documentation for the API I created and was very surprised at my naming method. Having briefly described to him the arguments previously cited, I realized that this would be repeated forever if I did not figure out how to properly name the resources.
To begin, briefly list the main arguments in favor of both options.
For a single number:
For the plural:
As you can see, the arguments are rather contradictory, and each one can come up with hundreds of counter arguments. I would add that I generally consider it rather pointless to refer to someone’s implementation: yes, Atlassian and Twitter are IT giants, but everyone can be wrong, especially considering that they do everything differently.
I don’t want to compile huge lists of resources that use different naming options for REST resources. Instead, I went to read Fielding's thesis, in which there are no specific conventions for naming. But there is a clear formulation of the concept of "resource identifier", which, in fact, is the subject of discussion. Here is what Fielding writes about her:
Well, that is, according to Fielding, there is a certain naming authority, which is engaged in the assignment of identifiers to resources, and it is responsible for the semantic correctness of the names. Fielding did not give us any guidelines on this very semantic correctness, believing that there is enough logic. If you search more, you can find his comment on a similar question, which shows the whole essence of his relationship to any REST refinements and standardizations:
That is, if you just generalize - "think for yourself, decide for yourself, and if it is standardized, you get nonsense and obyazalovka." Well, generally speaking, such an approach to this question is much better than forcing far-fetched standards and specifications, although it causes the appearance of many different implementations and approaches, but is not this really a sign of “free-as-in-free- speech? architecture?
Summarizing, we can say that there are no wrong approaches to the implementation of REST in the sense of naming resources. However, the following should be considered:
Thanks for attention!
Sources:
Immediately I warn you that this article is not an example of implementation, there is no code here at all. It is rather a reflection on the topic of REST, aggregating sources known to me, so that those who also face my problem do not have to search for a long time for a guide to action.
The reason for writing this article was a dispute with my colleague about the naming of REST entities: he argued that it was necessary to call them in the plural, for example,
books , I thought (and I think) that this is illogical, and defended the book option. I admit, we both went the wrong way - instead of finding the original documentation for the REST architecture, written by its creator R. Fielding as far back as 2000 (I’ll give you a link at the end), we first began to invent rationales for our positions, and then just began to look as it is done in large companies and, after sorting through several options, they found that mine is more common, and decided to end the dispute.')
All anything, but the same discussion was repeated a month later with another colleague who opened the documentation for the API I created and was very surprised at my naming method. Having briefly described to him the arguments previously cited, I realized that this would be repeated forever if I did not figure out how to properly name the resources.
To begin, briefly list the main arguments in favor of both options.
For a single number:
- Same 'resource identifier', but not 'resources identifier'!
- But Atlassian like this: docs.atlassian.com/atlassian-confluence/REST/latest-server
- In the description of the models there is no entity
books!
For the plural:
- The table in the database, most likely, is called in the plural!
- But on Twitter like this: dev.twitter.com/overview/api/tweets
- www.restapitutorial.com/lessons/restfulresourcenaming.html
As you can see, the arguments are rather contradictory, and each one can come up with hundreds of counter arguments. I would add that I generally consider it rather pointless to refer to someone’s implementation: yes, Atlassian and Twitter are IT giants, but everyone can be wrong, especially considering that they do everything differently.
I don’t want to compile huge lists of resources that use different naming options for REST resources. Instead, I went to read Fielding's thesis, in which there are no specific conventions for naming. But there is a clear formulation of the concept of "resource identifier", which, in fact, is the subject of discussion. Here is what Fielding writes about her:
REST uses a resource identifier involved in an interaction between components. The REST connectors provide access to the resource. It has been determined that it has been responsible for the mapping over time.
Well, that is, according to Fielding, there is a certain naming authority, which is engaged in the assignment of identifiers to resources, and it is responsible for the semantic correctness of the names. Fielding did not give us any guidelines on this very semantic correctness, believing that there is enough logic. If you search more, you can find his comment on a similar question, which shows the whole essence of his relationship to any REST refinements and standardizations:
It was a question of the dissertation of the dissertation. them (and their resulting trade-offs). It is almost never wasted, even when it is poorly informed.
...
...
the least common
denominator of misinformed "best practice" based upon whatever Microsoft
chose to implement in its last release. The IETF has made a habit of
that recently.
That is, if you just generalize - "think for yourself, decide for yourself, and if it is standardized, you get nonsense and obyazalovka." Well, generally speaking, such an approach to this question is much better than forcing far-fetched standards and specifications, although it causes the appearance of many different implementations and approaches, but is not this really a sign of “free-as-in-free- speech? architecture?
Summarizing, we can say that there are no wrong approaches to the implementation of REST in the sense of naming resources. However, the following should be considered:
- In the original description of the REST, the concept of “resource identifier” is described as a unique identifier that uniquely identifies a resource. What kind of identifier - ID, name or hash string representation - is not specified, this question is left to the discretion of the developers with the only condition: maintaining the semantic integrity of the architecture throughout the existence of the system.
- It is necessary to make the architecture understandable for the user. Internal implementation features - such as the name of the table in the database or the name of the entity in the description of ORM models - should fade into the background, and ideally should not be considered at all.
- Taking as an example the realization of a popular resource is undoubtedly convenient. But it is always necessary to remember that the dogmatic following of others' implementations in the future leads to arguments about anything.
Thanks for attention!
Sources:
Source: https://habr.com/ru/post/331064/
All Articles