Is REST an API, or: REST vs Java Interface?

Question

I had a discussion with a co-worker, he really fancies REST a lot, but I still have to be convinced of the benefits.

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.

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.

• In REST, it would call for example http://server/book/21 , get returned an arbitrary payload and deserialise it into a Book object.
• Using the RESTeasy client, we have an interface BookService with a method Book getBook(int bookId) , we simply call getBook(21) and get returned a Book object.

The point I am trying to make is that BookService 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 Book 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).

Another thing. I mentioned books and authors.

When using interfaces, you can just have a BookService returning Book s and an AuthorService returning Author s. A Book could have a property authorId and you can get an Author object by invoking Author getAuthor(int authorId) .

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?

And when mixing the two, strange things can happen. If I want to just get a Book by id, I might invoke the BookService (which internally translates to a REST call any way) and get a nice Book object. But then if I want to get author information, I have this String authorLink , which I have to follow to get my Author object. But conversely when my starting point is an Author and retrieve it using the AuthorService , I get links to books the author wrote, in a collection of strings (URLs) pointing to book objects.

So why is REST considered an API? Why should I prefer REST over well-defined (Java) interfaces? And how do I intermix the two?

Answer 1

Check out Hypermedia APIs on a search engine of your choice.

There is some good literature out there that will explain how you "know" what to invoke, with what request. In particular HATEOS .

Why Hypermedia APIs? REST is a pretty loose and watered down term. Often implemented incorrectly. There is a recent surge to try and clear up this confusion, hence the "new" terminology. When done correctly, you'll get the power of a REST (see Hypermedia API) service with the nice style interface that you are familiar with using the likes of strongly typed services (ala SOAP, RPC) in Java/.NET

Answer 2

Nobody is using REST in the way envisioned by Roy Fielding, for whatever reason. So it's impractical. For lazy people, that's enough to not have to think about it.

Apparently the industry is obsessed with inventing different names for RPC.

Answer 3

REST is not an API, but more of an architecture. REST is used to communicate between 2 different systems over existing HTTP protocols. REST makes much sense for many things, maybe in your case you do not need to be using it.

Answer 4

In a nutshell, a REST API is flexible for other programming languages.

I'm not familiar with RESTEasy but am familiar with RESTful services. There is no standard for REST. Most REST services publish how to interact with their REST API. What URLs (resources) are available, the content type to be sent and the type that will be returned. Good ones will also publish what http status codes will be returned and how to handle errors. In your case I wonder exactly what the REST Easy client is doing. Is it just converting the API call into an HTTP request and handling everything for the developer?

We document our REST API calls and provide a jar file with all the models. The models use JAXB annotations so developers don't need to know everything about the XML or JSON that is returned from the service. That is if they are using Java and our models. The nice thing about publishing and documenting the API is that developers of other languages can use the service provided they can make HTTP requests. This allows developers to develop client apps in virtually any programming language. (Lately seems to be more C# implementations).

In addition to providing the jar file of the models we provide XSD in our documentation for the non-Java developers.

Answer 5

if you think about REST (architectural not design or coding style) about tool for building distributed applications/systems than it's main intent to use well known and proven concept (on world wide web) for managing application state and than it makes sense to use it in some situations.

when you want to move some processing/computation from one application to some remote host (let say retrieving list of books) you can do that by serializing your method call (GetBooks) into SOAP message, and then add that message in http request etc.. or you can just call GET /books.. In some situations it's much cheaper to use ti on second way. if I mentioned some other things like resource caching which is part of infrastructure rather than it's implemented explicitly or flexibility when you want different representations of same resource, then it would even make more sense.

if some service uses REST style and it's written carefully (like any API) it's easy to understand and consume. also these kind of services can be easily consumed from different type of clients (javascript, php, ..) where is no frameworks like JAX-WS or WCF.

To simplify, you could think about REST service as book shelve, from where you can get some books(resources), where you can post new books or put one that you got .. if each resource has meaning in terms of problem domain and if resource representation contains links to related resources than i don't see the problem of understanding/consuming it.

Answer 6

You're misunderstanding a crucial part of REST. In a well-designed RESTful system, two things must be very well documented:

1. The entry point (or "cool" URIs) that you use to begin interacting with the system
2. The schema for the payload data sent within requests and returned within responses (in HTTP terms, these are the media types)

Give me just those two things , and I'll be able to build a client to your RESTful API. Starting at #1 and using knowledge of #2 to find my way around your system's API "hyperlinks", I will be able to find the resources I need.

Knowing your system's Book representation will allow me to make a GET call to retrieve one and understand it, or make a POST or PUT call to create one. HTTP supports those verbs out of the box, I just need to know what gets sent over the wire (and #2 tells me that).

If I don't like XML I can try asking the server if I can speak JSON instead, and HTTP supports that kind of content negotiation out of the box.

REST isn't magic fairy dust made by unicorns, and it won't solve your problems simply by virtue of being used. It is however a common-sense architecture that tries to make use of existing well-proven, well-understood, scalable and flexible technologies and approaches.

Answer 7

ReST is an architectural style, not an API.

Few advantages you get using ReST

1. Multiple response type capability (Eg: JSON, XML) ReST is not bound to XML like SOAP
2. Using JSON makes your payload light weight and your service is faster
3. Much easier to develop and test
4. ReST uses plain HTTP, so no proxy related issues

Regarding the service definition you can have a wadl file generated for your ReST service to see the full options. Most server autogenerate these. The services needs to be well documented whether it is SOAP or ReST. You can check the LinkedIn ReST API .

The only advantage i see for SOAP is the security features that SOAP can provide. But not all aplications need that level of security.