11

A full REST api like with Java's jax-rs contains definitions for defining a path for a resource, uses the full GET, POST, PUT requests.

But typically when I encounter a REST API, it is typically a standard HTTP GET request and the response is a JSON output. It seems like the meat of a real-world REST request is using JSON output but the true definition of REST allows for XML, JSON or other output types.

For example, the twitter API has "JSON" output, they use a GET request and here are some of the URL's:

https://dev.twitter.com/docs/api/1.1/get/search/tweets

And you can still use the "GET" parameters to modify the request. It seems like the twitter 'search/tweets' function is just a simple http request with a well defined URI path that happens to return a JSON response. Is that really REST?

What is a REST api to you?

On Jax-rs http://en.wikipedia.org/wiki/Java_API_for_RESTful_Web_Services

(Sorry if this is slightly subjective or anecdotal but I believe developers were wondering about this)

Berlin Brown
  • 11,504
  • 37
  • 135
  • 203
  • FWIW, it looks like Twitter, like other REST services, supports multiple output formats. For JSON - https://api.twitter.com/1.1/search/tweets.json For XML - https://api.twitter.com/1.1/search/tweets.xml – EJK Feb 26 '13 at 04:50
  • take a look at this http://stackoverflow.com/questions/3536893/what-are-the-pros-and-cons-of-xml-and-json – Drogba Feb 26 '13 at 04:51
  • http://stackoverflow.com/questions/1743532/why-is-everyone-choosing-json-over-xml-for-jquery – Ravi Gadag Feb 26 '13 at 04:52

5 Answers5

7

REST (Representational State Transfer) is a vague architectural design pattern which was first written about in a paper by Roy Fieldings (aka the guy who created HTTP).

Most of the time (99% of the time) when somebody wants a REST API they mean they want a web API where they send a Request containing an HTTP verb and a URL which describes the location of a Resource that will be acted upon by the HTTP verb. The web server then performs the requested verb on the Resource and sends back a Response back to the user. The Response will usually (depending on the HTTP verb used) contain a Representation of the resulting Resource. Resources can be represented as HTML, JSON, XML or a number of other different mime types.

Which representation used in the response doesn't really indicate whether an API is RESTful or not; it's how well the interface's URLs are structured and how the web server's behaviors are defined using the HTTP Verbs. A properly compliant REST API should use a GET verb to only read a resource, a POST verb to modify a resource, a PUT to add/replace a resource, and a DELETE to remove a resource. A more formal definition of the expected verb behaviors are listed in the HTTP Specification.

Darwyn
  • 4,696
  • 3
  • 25
  • 26
  • Good answer, I guess I was confused about so-called REST apis in the public like the twitter API which seems to break some of the REST rules. And I haven't ever seen a public API use the PUT or DELETE requests. There also isn't anything stop anyone from just having json output, GET request and calling it REST even if the architecture of the URLs aren't designed to be REST. – Berlin Brown Feb 26 '13 at 07:11
5

REST is (in a nutshell) a paradigm that resources should be accessible through a URI and that HTTP-like verbs can be used to manipulate them (that is to say, HTTP was designed with REST principles in mind). This is, say, in contrast to having one URI for your app and POSTing a data payload to tell the server what you want to achieve.

With a rough analogy, a filesystem is usually RESTful. Different resources live at different addresses (directories) that are easy to access and write to, despite not being necessarily stored on disk in a fashion that reflects the path. Alternatively, most databases are not RESTful - you connect to the database and access the data through a declarative API, rather than finding the data by a location.

As far as what the resource is - HTML, JSON, a video of a waterskiing squirrel - that is a different level of abstraction than adhering to RESTful principles.

Matt
  • 10,434
  • 1
  • 36
  • 45
  • It seems like a very, very loose standard if you we want to call it that. I guess I am trying to ask, why not just call it a HTTP request. Are well named URL's the basis for a particular architecture. When I look at the twitter API "web-service", it seems like just that, a HTTP GET request, JSON output with a well-named URI path? I guess I am being too pedantic about this. – Berlin Brown Feb 26 '13 at 04:51
  • It is indeed loose: more like a best practice than a strict set of rules. A key thing to understand is that the statement "a HTTP request" sort of encodes within it the RESTful principles that went into designing HTTP. It's such a common practice to address resources this way that it seems obvious to us now - but it wasn't always so. Many different data transfer mechanisms on the internet - like streaming video - are not RESTful. Can you imagine the world without URLs, where your browser has to understand a different data format for every server? Totally gross. – Matt Feb 26 '13 at 05:02
  • @BerlinBrown - actually, your not being pedantic enough! REST is based on HTTP, but the core of the specification has to do with *alot* more than the communication transport. I recommend reading [Fielding's original dissertation](http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm) on the subject, as a start. It describes key principles of uniform interfaces, representational state, statelessness, and other key RESTful principles. – Perception Feb 26 '13 at 05:03
0

REST is a pretty "loose" standard, but JSON is a reasonable format to standardize around. My only major concern with JSON overall is that it doesn't have a method for explicitly defining its character encoding the way XML does. As for the verbs, sticking to meaningful usages of the verbs is nice, but they don't necessarily map one for one in every situation, so as usual, use common sense :)

Ian McMahon
  • 1,660
  • 11
  • 13
0

It can be JSON, it can be XML. JSON is not exactly industry "standard," but many developers like it (including me) because it's lightweight and easy.

Matthew Quiros
  • 13,385
  • 12
  • 87
  • 132
0

That's pretty much it. REST is designed to be simple. The gist of it is that each url corresponds to a unique resource. The format of the resource is commonly json, but can be anything, and is typically determined by the "extension" or "format" part of the url. For example, "/posts/1.json" and "/posts/1.xml" are just two different representations of the same logical resource, formatted in json and xml, respectively. Another common trait of a RESTful interface is the use of HTTP verbs such as GET, PUT, and POST for retrieving, modifying and creating new resources. That's pretty much all there is to it.

mockaroodev
  • 2,031
  • 1
  • 20
  • 24