[Discussion] Define Rest API design best practise and naming convention

[davidjovanovic]

Some suggestions:

• Try to use plural nouns to represent resources and collections (e.g. /users)

  • Exception: a "concept" that is obviously singular

• Try to use lowercase letters and hyphens to improve the readability (instead of camelCase or underscores)

• Try to avoid verbs and try to use HTTP methods for actions e.g. use GET /users to list all users, instead of "getUsers"

In the event that actions that are not directly related to a resource are to be performed, one of the following examples can be envisaged as a solution:

1. it is possible to use a noun that identifies the resource obtained at the end of the action (e.g /negotiations/{pId}/agreement)

2. it's possible to use sub-collection resources (e.g. /users/{userId}/profiles)

3. it's possible to pass the action as a parameter for a POST method

     POST /services/{id}
     {
         "action": "execute",
          ...
     }

4. instead of invoking /services/{id}/execute, it's possible to create a resource for all the actions that currently can be executed and then invoke something like /services/{serviceId}/actions/{actionId}