Search code examples
restrestful-urlrestful-architecture

Rest 'guidelines' make the API design difficult

I am trying to create an API for my Rest services and i am struggling with the design rules that i try to follow. In generally i am trying to follow (among others) these guidelines:

  1. Don't use verbs in the URIs
  2. Don't use query parameters when altering states
  3. Use plural
  4. Don't use camel case

Now, i have to model something like the following:

  • Get all departments of a company
  • Get a department of a company
  • Delete all deprtaments of a company
  • Delete a department of a company

I am trying something like this:

GET company/departments
GET company/departments/<depName>
DELETE company/departments
DELETE company/departments  {body: department name}

The above, follows the guidelines that i have mentioned, but i really don't think that the resulted URIs are good. Especially the fourth, does a different job and has the same URI as the third.

This is a common problem for me, and i encounter it many times when i am designing REST services. The result is that i always break some designing principles to achieve what i want or make uglier URIs (for example: DELETE company/departments/department).

So the actual question is:

In my design, how can i delete a single department with a Restfull-like URI?

Solution

  • A URL consists of several parts:

    http://example.com/company/departments/12345?arg1=this&arg2=that

    http: is the scheme. //example.com is the host. /company/departments/12345 is the path, ?arg1=this&arg2=that is the query string, consisting of two parameters: arg1 and arg2. There's another aspect, called matrix arguments, which won't be discussed here.

    When REST talks about URLs, it refers to the entire thing. Not parts of it. To REST the entire URL is treated as an opaque blob.

    That means REST doesn't care about any particular part: the scheme, the host, the path, or the arguments.

    ftp://127.0.0.1/E280F814-1524-41D5-8735-43D8414AE242 is a perfectly fine URL as far as REST is concerned.

    So as far as REST is concerned, it doesn't give a rip what path you use in your URL or whether you use parameters or not.

    That said, the recommendations against parameters in a URL is because sometimes, caches don't cache paramaterized URLs properly. Thus the preference for /company/department/12345 over /company/department?id=12345.

    The 12345 in the path is not a parameter. Its the name of the resource. Just like starwars.mp4 above is not a parameter, nor is E280F814-1524-41D5-8735-43D8414AE242. They're just names. The only folks that actually care are people. The computer doesn't care, the internet doesn't care, REST doesn't care. To them, it's just all bits.

    So it sounds like a simple miscommunication that you're fighting. Try not to stress over it too much. Too much weight is pressed on URL naming anyway, when it's the resources and their representations that actually matter.