Sorted By: Month (6) and Year (2014)


I have been designing HTTP APIs (Web APIs, if you want to call it that) for a fair amount of time now and I have been handling the HTTP DELETE operations the same way every time. Here is a sample.

HTTP GET Request to get the car:

GET http://localhost:25135/api/cars/3 HTTP/1.1
User-Agent: Fiddler
Accept: application/json
Host: localhost:25135

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Wed, 25 Jun 2014 12:36:48 GMT
Content-Length: 68

{"Id":3,"Make":"Make3","Model":"Model1","Year":2009,"Price":67437.0}

HTTP DELETE Request to delete the car:

DELETE http://localhost:25135/api/cars/3 HTTP/1.1
User-Agent: Fiddler
Accept: application/json
Host: localhost:25135

HTTP/1.1 204 No Content
Date: Wed, 25 Jun 2014 12:36:52 GMT

Now we can see that the car is removed as I received 204 for my HTTP DELETE request. Let's send another HTTP DELETE to same resource.

HTTP DELETE Request to delete the car and receive 404:

DELETE http://localhost:25135/api/cars/3 HTTP/1.1
User-Agent: Fiddler
Accept: application/json
Host: localhost:25135

HTTP/1.1 404 Not Found
Date: Wed, 25 Jun 2014 12:36:52 GMT
Content-Length: 0

I received 404 because /api/cars/3 is not a URI which points to a resource in my system. This is not a problem at all and it's a correct way of handling the case as I have been doing for long time now. The idempotency is also preserved because how many times you send this HTTP DELETE request, additional changes to the state of the server will not occur because the resource is already removed. So, the additional HTTP DELETE requests will just do nothing.

However, here is the question in my mind: what is the real intend of the HTTP DELETE request?

  • Ensuring the resource is removed with the given HTTP DELETE request.
  • Ensuring the resource is removed.

Here is what HTTP 1.1 spec says about HTTP DELETE:

The DELETE method requests that the origin server delete the resource identified by the Request-URI. This method MAY be overridden by human intervention (or other means) on the origin server. The client cannot be guaranteed that the operation has been carried out, even if the status code returned from the origin server indicates that the action has been completed successfully. However, the server SHOULD NOT indicate success unless, at the time the response is given, it intends to delete the resource or move it to an inaccessible location.

A successful response SHOULD be 200 (OK) if the response includes an entity describing the status, 202 (Accepted) if the action has not yet been enacted, or 204 (No Content) if the action has been enacted but the response does not include an entity.

If the request passes through a cache and the Request-URI identifies one or more currently cached entities, those entries SHOULD be treated as stale. Responses to this method are not cacheable.

I don't know about you but I'm unable to figure out which two of my above intends is specified here. However, I think that the HTTP DELETE request’s intend is to ensure that the resource is removed and cannot be accessible anymore. What does this mean to my application? It means that if an HTTP DELETE operation succeeds, return a success status code (200, 202 or 204). If the resource is already removed and you receive an HTTP DELETE request for that resource, return 200 or 204 in that case; not 404. This seems more semantic to me and it is certainly be more easy for the API consumers.

What do you think?

References



This year, I decided not to miss on awesome developer conference NDC in Oslo and well, I attended! I'm actually still in Norway and I can tell that by looking at my pocket. I'm basically broken in terms of money :) Don't go to conferences if the city is ranked at the top of the World's most expensive cities (kidding, take a loan and go to NDC). If you miss this awesome developer conference, don't worry that much. The videos are already available online and I'm actually watching couple of the ones that I missed.

During the event, a few things were highlighted by many people over and over again which also made sense to me. Since this was a developer conference crowded by the World's top notch software developers, these are worth pointing out as bullet points for developers like me:

  • Mobile matters a lot (kind of obvious but worth highlighting it)!
  • JavaScript is big! No matter what programming language you use and what kind of development you do, it's going to end pretty badly for you if you keep ignoring JavaScript.
  • Learn a functional programming language. If you are a developer, you should (and I should) learn a functional programming language. It's kind of unavoidable in a World where concurrency matters this much.
  • Don't develop for the management, develop for the users of your product and your team mates (current and future).
  • SQL is still there but practically dead (there I said it!).
  • This is only what I felt during these days: you cannot survive in a software industry if you only know one general purpose programming language (well, you probably will but I don't think you will really *survive*. Catching my drift?).
  • Swift (not Taylor Swift) is a joke but it will be loved.

These are just my thoughts during these 3 days and the time will tell us whether those are actually valid points.

Tags