title: Is REST an API, or: REST vs Java Interface?
body: <p>I had a discussion with a co-worker, he really fancies REST a lot, but I still have to be convinced of the benefits.</p>
  
  <p>My main issue is that I do not really see REST as an API, or interface in general, from a consuming application point of view. Let me elaborate. We have two applications where one calls the other using a RESTful API. This is implemented using JAX-RS and RESTeasy. Using RESTeasy though, it's pretty trivial to also generate a REST client based off of the interface.</p>
  
  <p>So let's say it's a system dealing with books and authors. The application needs to know about a book and let's assume it already knows some ID.</p>
  
  <ul>
  <li>In REST, it would call for example <code>http://server/book/21</code>, get returned an arbitrary payload and deserialise it into a <code>Book</code> object.</li>
  <li>Using the RESTeasy client, we have an interface <code>BookService</code> with a method <code>Book getBook(int bookId)</code>, we simply call <code>getBook(21)</code> and get returned a <code>Book</code> object.</li>
  </ul>
  
  <p>The point I am trying to make is that <code>BookService</code> is a well-defined interface, where you (as a programmer) can easily see that the argument it expects is an identifier and it will return a <code>Book</code> object. Using "just REST", we visit some URL, and we get returned arbitrary data. There is no well-defined interface, you do not know how to build the URL without knowing internal URL information from the server and you have to "manually" parse XML (hopefully using an XSD).</p>
  
  <p>Another thing. I mentioned books and authors.</p>
  
  <p>When using interfaces, you can just have a <code>BookService</code> returning <code>Book</code>s and an <code>AuthorService</code> returning <code>Author</code>s. A <code>Book</code> could have a property <code>authorId</code> and you can get an <code>Author</code> object by invoking <code>Author getAuthor(int authorId)</code>.</p>
  
  <p>When using REST, you call the book URL and get returned some information about authors, including links to authors. Then you follow the link to get more information about authors. But how will you know where exactly to find this link? And the same questions as before arise: how to construct the link, how do I know how to parse the return data?</p>
  
  <p>And when mixing the two, strange things can happen. If I want to just get a <code>Book</code> by id, I might invoke the <code>BookService</code> (which internally translates to a REST call any way) and get a nice <code>Book</code> object. But then if I want to get author information, I have this <code>String authorLink</code>, which I have to follow to get my <code>Author</code> object. But conversely when my starting point is an <code>Author</code> and retrieve it using the <code>AuthorService</code>, I get links to books the author wrote, in a collection of strings (URLs) pointing to book objects.</p>
  
  <p>So why is REST considered an API? Why should I prefer REST over well-defined (Java) interfaces? And how do I intermix the two?</p>