3

I'm new to this game so I might be misunderstanding things. Actually, if someone tells me that I'm misunderstanding things, it will be a favor. Maybe this person will be considerate enough to show me the right path. But...

One of the "guidelines" or "best practices" of REST as it applies to Web Services (http://en.wikipedia.org/wiki/Representational_state_transfer#Applied_to_web_services) is that you should use the proper HTTP methods when making calls (did I misunderstand it?) to REST API's.

But looking at many API implementations on the web, what I see is that 100% of the calls made to them are actually GET calls that, depending on their URI, will be interpreted by the API as being of one of the HTTP verbs or methods.

So, for example, looking at the REST API documentation for Twitter (https://dev.twitter.com/rest/public) which, in principle, only defines two verbs/methods (GET and POST), actually have all calls sent as GET and, based on the URI in the GET call, are interpreted by the API and acted upon.

Example:

GET statuses/lookup: https://api.twitter.com/1.1/statuses/lookup.json

POST statuses/update (PUT?): https://api.twitter.com/1.1/statuses/update.json

In both cases, the call itself was made using GET and the last part of the URI defined it as a real GET or as a POST.

In summary, to be truly RESTful, shouldn't client side implementations of REST API's for web services use the proper HTTP verbs/methods?

What am I missing?

Dentra Andres
  • 371
  • 1
  • 7
  • 18
  • *"In both cases, the call itself was made using GET"* – what does that mean exactly? Do you mean the API accepts regular GET requests even though the documentation specifies POST? Who is "making these calls"? I'm confused as to what you're trying to say. – deceze Mar 19 '15 at 17:51
  • this may help; Hypermedia support is crucial: https://docs.google.com/presentation/d/16bqtQz_sa_YgO6wlC8p-YK-ZTMWmrvyZiub7FupTT5M/edit#slide=id.p – Filip Mar 19 '15 at 18:31
  • 1
    and this: patterns and anti-patterns: https://docs.google.com/presentation/d/1zhfqu7Wuy67J5fgz2jGh2I-kUpQblZpoWj3IQfp4yts/edit#slide=id.p – Filip Mar 19 '15 at 18:31
  • @filip26 Great resources. From the name, I'm assuming you are the author. Congratulations. – acdcjunior Mar 19 '15 at 19:54
  • http://nishantshukla001webservices.blogspot.in/2015/09/webservices-soap-vs-rest-json-vs-xml.html – Nico Apr 15 '16 at 11:34

5 Answers5

11

You're missing a lot, but don't worry about it, most people are.

The fact is that very few so-called REST APIs publicly available on the internet are really RESTful, mostly because they are not hypertext driven. REST became a buzzword to refer to any HTTP API that isn't SOAP, so don't expect for an API to really be RESTful just because it says it's a REST API. I recommend reading this answer.

From my experience, most API developers aren't aware what REST really is and believe any HTTP API that uses HTTP and avoids verbs in URIs is REST.

REST is defined by a set of constraints. Among them is the uniform interface, which in simple terms means that you should not change the expected behavior of the underlying protocol. REST isn't coupled to any particular protocol, but since it's common to be used with HTTP, they get convoluted sometimes.

HTTP has very well defined semantics for the GET, POST, PUT, DELETE, PATCH and HEAD methods, and the POST method has its semantics determined by the server. Ideally, a REST API should respond to the methods other than POST exactly as determined in the RFC 7231, but as you noticed, there are many APIs who call themselves REST but don't do that. This happens for many reasons. Sometimes there's a simple misunderstanding about the correct semantics, or it's done to keep consistency, or because of backwards compatibility with intermediaries that don't support all methods, and many other reasons.

So, there's a lot more that has to be done to be truly RESTful other than using the HTTP methods correctly. If an API doesn't get even that right, it needs to find another buzzword, because it's definitely not REST.

Community
  • 1
  • 1
Pedro Werneck
  • 40,902
  • 7
  • 64
  • 85
  • Great reading. The hypertext part is definitely important (well, Roy said it himself, doesn't get much more direct than that), and it is frequently missed (heck, how many REST APIs have you seem that really use HATEOAS?!). Great reference to the RFC 7231 too. Very enlightening. – acdcjunior Mar 20 '15 at 14:58
2

You are correct. If they want to be "RESTful", their API should respect the semantics of each HTTP method.

Roughly, REST is about method Information (what the server should do), scoping information (where the server should do it) and, I almost forgot to mention, hypermedia driven (make sure you check @PedroWerneck's great answer to this question as it talks about it a little more and referecences a blog post from Fielding on the matter).

What the API you mentioned does is have both method and scoping information in the URL. That would not fit the RESTful architecture very well, as it, in general terms, tells us to:

  • 1) use the HTTP methods the proper way (respecting their properties, such as idempotency and others), and
  • 2) use unique URIs to identify unique resources.

Point 1 says "use HTTP methods to convey method information" and point 2 says "use URIs to convey scoping information".

Again, if an API uses GET with a specific parameter in the URI to do something (and not get something), then it is using URI to convey method information.

Now, don't be alarmed. Most APIs out there are just RESTful-ish (like twitter's of flickr's), meaning they are an animal between REST and something else. That is not bad per se, it just means they will not fully benefit from what RESTful architectures (and HTTP) have to offer.

Remember that being RESTful isn't just a matter of fashion, it does have its benefits, such as statelesness, adressability, and so on. And those can only be fully achieved by using the HTTP verbs like they were supposed to be used.

About using POST instead of PUT, considering they have different properties (PUT is idempotent, POST is not), it is not bad to use POST, as long as it is uniformly designed, that is, a programmer should not wonder what POST will do for each and every URI in the API: they all should behave the same. (PUT does not suffer from that because it already is uniform.) I talked a little more about this - and quoted Roy Fielding's say on it - in another question (check out the "Wrapping Up" part).

Community
  • 1
  • 1
acdcjunior
  • 132,397
  • 37
  • 331
  • 304
  • Excelent answer, but I disagree in one minor point. POST doesn't have to be uniformly designed across an API. The semantics of the POST method are determined by the targeted resource, so it's perfectly fine to have different behavior for each URI, as long as its properly documented for that media-type. – Pedro Werneck Mar 20 '15 at 04:37
  • @PedroWerneck Yeah, I think if your uniform definition of `POST` is that each resource would have a different meaning for it, I guess it is OK. I took that definition (of uniformity) from Roy's post on his blog, ["It's okay to use POST"](http://roy.gbiv.com/untangled/2009/it-is-okay-to-use-post), did you get a chance to check it out? Maybe we could reach a point of agreement (I'd be interested in that, no problem if I have to correct myself, since we are here to learn, right? :). – acdcjunior Mar 20 '15 at 14:51
  • Yes, that's precisely where I got my definition from, so maybe we're just saying the same thing in different words. The uniform definition I have for POST is that it submits the enclosed payload to be processed by the targeted resource, contrary to PUT, for instance, which asks the server to completely replace the targeted resource. What the target resource does with the POSTed payload is documented by the media type. As Roy says in that article, POST is the method to go for any action that isn't worth standardizing. – Pedro Werneck Mar 20 '15 at 15:12
2

I can't exactly tell what your question is, but I believe there are some concepts that will help you. Allow me to elaborate...

You are correct that many APIs use a limited number of HTTP "verbs" in their API. GET/POST are the most common. PUT less so, and then all others (DELETE, HEAD, OPTIONS etc) are used with vanishing probabilities.

Dropbox Core API for file uploads allows optional PUT / POST and their stated reason is "For compatibility with browser environments, the POST HTTP method is also recognized."

Indeed the limitation is the browser. Popular web servers have no problem with all HTTP request methods and even made up ones. After all, the request method is just some string with regard to the web server.

HTML4 and HTML5 only allow GET and POST requests for form requests. If you want your API to be used through a browser at all - and hey why not, it sounds like a useful thing - then you're limited to GET/POST. For a useful discussion on this see: https://softwareengineering.stackexchange.com/questions/114156/why-are-there-are-no-put-and-delete-methods-on-html-forms

Further complicating things is the fact that REST is not an industry standard. There exists no RFC, ISO or other document detailing what a "compliant" implementation must and must not do. While many folks have been playing concepts related to REST for some time, the REST concept was "invented" in the PhD disseration of Roy Fielding. A fantastic read if you're interested in such things.

Yes, according to REST, APIs should be using the correct verbs. However, as long as the documentation is clear and all GET requests are idempotent, then life should continue smoothly.

(Source: I wrote PipeThru.com which integrates 40+ APIs, Dropbox and Twitter included)

Community
  • 1
  • 1
Andy Jones
  • 6,205
  • 4
  • 31
  • 47
2

I think that this link could give you some hints about the design of RESTful services / Web API: https://templth.wordpress.com/2014/12/15/designing-a-web-api/.

It's clear that not all Web services that claim to be RESTful are really RESTful ;-)

To be short, RESTful services should leverage HTTP methods for what they are designed for:

  • method GET: return the state of a resource
  • method POST: execute an action (creation of an element in a resource list, ...)
  • method PUT: update the complete state of a resource
  • method PATCH: update partially the state of a resource
  • method DELETE: delete a resource

You need to be also to be aware that they can apply at different levels, so methods won't do the same things:

  • a list resource (for example, path /elements)
  • an element resource (for example, path /elements/{elementid})
  • a field of an element resource (for example, path elements/{elementid}/fieldname). This is convenient to manage field values with multiple cardinality. You don't have to send the complete value of the fields (whole list) but add / remove elements from it.

Another important thing is to leverage HTTP headers. For example, the header Accept for content negotiation...

I find the Web API of Github well designed and its documentation is also great. You could browse it to make you an idea. See its documentation here: https://developer.github.com/v3/.

Hope it helps you, Thierry

Thierry Templier
  • 198,364
  • 44
  • 396
  • 360
0

Consider looking at REST Richardson Maturity Model topic.

This specification is about how much RESTful particular API is:

Level 0: Simple GET and POST request to descriptive url

/getUserByName?name=Greg

Level 1: Divide all content in resources and define actions in resource group

/user/getByName?name=Greg

Level 2: Proper use of HTTP verbs.

GET /user/Greg

Level 3: Use hypermedia controls

Different APIs in interent implement different maturity level of REST. That's why some APIs don't support all HTTP features.

suvroc
  • 3,058
  • 1
  • 15
  • 29