Naming convention: nouns and plurals

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)

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.