Search code examples
restnaming-conventionsrestful-architecture

Restful API naming conventions

So me and my boss aren't agreeing here and can't find any information on it. Scenario: I want to get all the users for a certain organisation. What should the URL be?

mydomain.com/users/by/organisation/{orgId}

OR

mydomain.com/organisation/{orgId}/users

Our arguments:

Case 1: The call is expected to return "users" and therefore the "resource" (first part of the call) should relate to it.

Case 2: The organisation "owns"/"is the parent of" the user and therefore the organisation should be first.

What are your thoughts?

UPDATE: I am not to worried about what comes after the mydomain.com/{resource}. The question relates mostly to whether the HTTP action (GET, POST, PUT, DELETE) should relate to the first resource mydomain.com/users or whether it should reflect the relationship mydomain.com/organisations/users/.

Solution

  • You are probably aware that REST has no strict rules, you are more or less free to implement it however you like, but here are my 2 cents

    mydomain.com/users/by/organisation/{orgId}

    However this sounds like a good url because it sort of tells you what it does by reading it, this is not a great idea. Normally, each url segment specifies a resource that exists or can exist.

    In this case, users represents one or more resources and so does organisation, but by does not, it's probably nothing more than a word to help clarify what the API does.

    The call is expected to return "users" and therefore the "resource" (first part of the call) should relate to it.

    A resource is not necessarily specified in the first part of the url. It can be the 2nd, 3rd or 10th if you want

    mydomain.com/organisation/{orgId}/users

    This looks much better but I think there is 1 point of improvement. You should rename organisation to organisations, to match users

    This

    mydomain.com/organisations/{orgId}

    then gets the organisation with id orgId, and

    mydomain.com/organisations/{orgId}/users

    gets all the users that belong to that organisation.

    To further narrow it down you could do

    mydomain.com/organisations/{orgId}/users/{userId}

    to get one specific user belonging to one specific organisation

    UPDATE: I am not to worried about what comes after the mydomain.com/{resource}. The question relates mostly to whether the HTTP action (GET, POST, PUT, DELETE) should relate to the first resource mydomain.com/users or whether it should reflect the relationship mydomain.com/organisations/users/.

    To answer your update:

    I already mentioned it above; A resource is not necessarily specified in the first part of the url.. If the quality of the url improves by shifting the wanted resource to the back of the url, go ahead and do so