CODEWITHSUNDEEP
apirestdesign-patternscrud
Nikola Z
Nikola Z

Reputation: 1

REST API resource naming suffix

Our project came into discussion about URI pattern for Rest API.

The basic idea is a better description / readability of the endpoints themselves, by adding CRUD elements practically as a suffix in the endpoint name.

So, examples (different examples without consistency for one project):

- GET    /api/v1/endpoint-names/read
- GET    /api/v1/endpoint-names/read/{id}
- GET    /api/v1/endpoint-names/read-paginated/{pageId}
- POST   /api/v1/endpoint-names/create
- PUT    /api/v1/endpoint-names/update-by-id/{id}
- DELETE /api/v1/endpoint-names/delete/{id}

I am aware of some recommendations, but I am interested in additional naming conventions / suggestions for web services with more complicated URI structures.

Or there is no real need for something like this?

Upvotes: 0

Views: 853

Answers (1)

VoiceOfUnreason
VoiceOfUnreason

Reputation: 57397

The basic idea is a better description / readability of the endpoints themselves, by adding CRUD elements practically as a suffix in the endpoint name.

Tradeoffs - among other things, you give up the benefits of general purpose cache invalidation when you use different resource identifiers for different kinds of edits.

Note the difference in language; REST doesn't have endpoints. Uniform resource identifiers identify resources -- think "web pages". We send information to a server by proposing changes to its resource model (adding/removing resources, or modifying the representations of those already present).

Part of the point here being that -- because we are all understanding messages the same way -- we can integrate the same general purpose capabilities (browsers, spiders, proxies) to do useful work

The implementation of that useful work is hidden behind this "it's all just documents" facade. See Webber 2011.

So when you create separate identifiers for each CRUD action

/foo/12345/read
/foo/12345/update

What you are hiding from the HTTP application is the fact that these are in fact the same information, and that messages sent to .../update modify the representations returned by .../read, which means that general purpose components can't know to update their caches automatically, and you miss out on some of that "web scale" that we've all been promised.

And that can be fine: maybe you prefer having unambiguous spellings in the logs that your operators read to having web friendly caching.

Upvotes: 0

Related Questions