search

Geonovum / KP-APIs

26 stars 40 forks source link

Paragraph 4.2.3: proposal singular for single resources #269

Closed middagj closed 3 years ago

middagj commented 5 years ago

In paragraph 4.2.3 the rule is established to use plural in the path for collections (e.g. /users) and item of collections (e.g. /users/31).

It doesn't say anything about resources that are single by nature. For example the current user in the GitLab API.

Our (Logius FBS) proposal is to extend this rule to specify single nouns for single resources. It follows the mentioned KISS principle in the paragraph and fits the REST approach of resources. See also StackOverflow for a discussion.

HenriKorver commented 5 years ago

Nice proposal! Can you work it out in a pull request?

middagj commented 5 years ago

Sure, no problem.

jasperroes commented 4 years ago

Vanwege de splitsing van het document was deze wijziging niet meer meegenomen, deze heb ik nu alsnog verwerkt in het nieuwe design rules document.

middagj commented 4 years ago

Ik weet niet of we hetzelfde bedoelen met singular resource.

Singular resource, describing an individual thing:

https://api.example.org/v1/gebouwen/3b9710c4-6614-467a-ab82-36822cf48db1 https://api.example.org/v1/vergunningen/d285e05c-6b01-45c3-92d8-5e19a946b66f

Het gaat ons juist om dingen die altijd alleen zijn, in tegenstelling tot collecties, zoals de huidige user in de GitLab API. Er is dus geen id meer in tegenstelling tot items uit de collectie. Zie ook de Rails guide. Ik kan uit de paragraaf nu niet halen wat het voorgestelde path is voor dit soort resources.

joostfarla commented 4 years ago

OK goed punt; dit zullen we nog verwerken!

joostfarla commented 4 years ago

Verwerkt, zie: https://geonovum.github.io/API-Designrules/#api-54