Search code examples
apirestmicroservicesmulti-tenantendpoint

URIs in REST API endpoints according to Restful practices

I am planning to have these endpoints for our REST APIs.

  1. PUT /tenant/:tenantId/users/save/:username

  2. POST /tenant/:tenantId/users/invite

  3. GET /tenant/:tenantId/users/fetch

  4. GET /tenant/:tenantId/users/fetch/:username

  5. PATCH /tenant/:tenantId/users/activate/:username

  6. POST /tenant/:tenantId/groups/save/

Verbs such as save/fetch/activate are from the consistency point of view. Are these RESTFul according to the REST principles? How should these be changed if at all? Any recommendations?

Solution

  • According to this REST Resource Naming Guide:

    RESTful URI should refer to a resource that is a thing (noun) instead of referring to an action (verb) because nouns have properties which verbs do not have – similar to resources have attributes.

    And also

    URIs should not be used to indicate that a CRUD function is performed. URIs should be used to uniquely identify resources and not any action upon them. HTTP request methods should be used to indicate which CRUD function is performed.

    So let's take your first URI as example

    PUT /tenant/:tenantId/users/save/:username

    Here you are using the verb save. As mentioned before you should not be indicating a CRUD operation in the URI, in this case using a POST would be more appropriate.Here is a guide with the purpose of each HTTP verb. Knowing this, I think that for example a more appropriate URI for that case would be something like

    POST /tenants/:tenantId/users/:username

    In this cases:

    GET /tenant/:tenantId/users/fetch

    GET /tenant/:tenantId/users/fetch/:username

    you should remove the fetch because you are already telling through the GET verb that data is being fetched. Same goes for the 6th example.

    But, this doesn't mean that you can't use verbs in your URIs, in fact there is a specific category called controller which as mentioned in the same guide:

    A controller resource models a procedural concept. Controller resources are like executable functions, with parameters and return values; inputs and outputs. Use “verb” to denote controller archetype.

    This controllers resources could go well (I asume) with for example your

    GET /tenant/:tenantId/users/activate/:username.

    But I would think that the verb activate should go last:

    GET /tenant/:tenantId/users/:username/activate