From fbe42ded19c2ee278403e5b399a989a367e4a4f2 Mon Sep 17 00:00:00 2001 From: Arialdo Martini Date: Wed, 22 Jan 2020 11:52:13 +0100 Subject: [PATCH] Naming convention: nouns and plurals --- docs/guidelines.md | 2 ++ docs/rest.md | 23 +++++++++++++++++++++-- 2 files changed, 23 insertions(+), 2 deletions(-) diff --git a/docs/guidelines.md b/docs/guidelines.md index faf491c..44bfbcd 100644 --- a/docs/guidelines.md +++ b/docs/guidelines.md @@ -19,6 +19,8 @@ We build web services according to [REST](rest.md) on HTTP, aiming to a [high ma [We build the API around business flows](rest.md#organize-the-API-around-resources). We avoid creating APIs that simply mirror the internal database structure. +We strive to adopt a [consistent naming convention](rest.md#naming-conventions). + ## References [Microsoft - Web API design](https://docs.microsoft.com/en-us/azure/architecture/best-practices/api-design) [Martin Fowler - Richardson Maturity Model](https://martinfowler.com/articles/richardsonMaturityModel.html) diff --git a/docs/rest.md b/docs/rest.md index 54333fc..6e2241f 100644 --- a/docs/rest.md +++ b/docs/rest.md @@ -55,7 +55,9 @@ We generally aim to design APIs of the highest level, but we compromise to use t We focus on the business entitites that the Web API exposes. -### URIs +### Naming conventions + +#### URIs Resource URIs are based on nouns (the resource) and not verbs (the operations on the resouce). For example: ``` @@ -65,9 +67,26 @@ Resource URIs are based on nouns (the resource) and not verbs (the operations on A resource doesn't have to be based on a single pthisical data item. For example, an order resource might be implemented internally as several tables in a database, but presented to the client as a single entity. We avoid creating APIs that simply mirror the internal structure of a database. A client should not be exposed to the internal implementation. -### Collections +All URIs are generally plural noums, regardless if they represent a collection or a single item. For example, the collectin of all orders might be: + +``` +[POST] https://mycompany.com/orders +``` + +while a single order might have the URI: + + +``` +[POST] https://mycompany.com/orders/12 +``` + +#### Collections Entities can be grouped together into collections. A collection is a pearatate resource from the item withing the collection, and therefore it must have its own identifier URI. For example, the following might represent the collection of orders: ``` https://mycompany.com/orders" ``` + +Each item in a collection has its own identifier URI. An HTTP GET request to that URI returns the deetails of that item. + +Collections must be paginated.