REST in Practice: Hypermedia and Systems Architecture

Author: Jim Webber, Savas Parastatidis, Ian Robinson
4.2
All Comments
TopTalkedBooks posted at August 20, 2017

A calculator service would be simple to model in a RESTful manner. The "R" in "CRUD" stands for "read", and there's no reason that "read" can't also mean "compute". So a simple Reverse Polish calculator service could be accessed via GET:

GET https://calc.com/rpnCalc?3&4&%2B
7

The URI scheme above simply adds three parameters to the GET request:

3
4
+ (URL-encoded as %2B)

That's an idempotent, safe and cacheable request. If this was an insanely complicated math query that took many minutes to compute I could route these queries to an out-of-the-box HTTP proxy and use it to instantly return any pre-computed values should the same URI be queried repeatedly.

Depending on the kinds of calculations you need to do, you could also POST a very complex query to a Calculator resource (passing in the query as the request body) and the server might return the URI to a "result" resource, which you can then GET to retrieve the results, and even paginate through them.

Secondly, what is the real advantage of using REST over SOAP if the logic of SOAP already makes complete sense?

I can access the above calculator service using a command-line tool like curl without building a complex piece of SOAP. I can code calls to it in seconds without having to use any third-party XML library or SOAP toolkit. I can use commodity tools like HTTP proxies to cache results and improve performance. I don't have to worry about SOAP interoperability or check for WS-I compatibility. If I use hyperlinks correctly then I can evolve and improve my service without affecting existing clients or having them to even recompile. There's no WSDL to version and no brittle contract which I have to maintain for years. The clients already know what GET/PUT/POST/DELETE do and I don't have to redefine or re-document their semantics. API clients that decide they'd prefer JSON instead of XML can get it using HTTP's inbuilt content-negotiation feature. I can do absolutely zero of these things with SOAP and Web Services.

Hey, if SOAP fits your needs, have at it. There are many benefits to using REST but they might not be appropriate to your situation. At the very least, learn about what REST can give you with a decent book like this one and then make your mind up after getting the full story.

TopTalkedBooks posted at August 20, 2017

REST

I understand the main idea of REST is extremely simple. We have used web browsers for years and we have seen how easy, flexible, performing, etc web sites are. HTML sites use hyperlinks and forms as the primary means of user interaction. Their main goal is to allow us, clients, to know only those links that we can use in the current state. And REST simply says 'why not use the same principles to drive computer rather than human clients through our application?' Combine this with the power of the WWW infrastructure and you'll get a killer tool for building great distributed applications.

Another possible explanation is for mathematically thinking people. Each application is basically a state machine with business logic actions being state transitions. The idea of REST is to map each transition onto some request to a resource and provide clients with links representing transitions available in the current state. Thus it models the state machine via representations and links. This is why it's called REpresentational State Transfer.

It's quite surprising that all answers seem to focus either on message format, or on HTTP verbs usage. In fact, the message format doesn't matter at all, REST can use any one provided that the service developer documents it. HTTP verbs only make a service a CRUD service, but not yet RESTful. What really turns a service into a REST service are hyperlinks (aka hypermedia controls) embedded into server responses together with data, and their amount must be enough for any client to choose the next action from those links.

Unfortunately, it's rather difficult to find correct info on REST on the Web, except for the Roy Fielding's thesis. (He's the one who derived REST). I would recommend the 'REST in Practice' book as it gives a comprehensive step-by-step tutorial on how to evolve from SOAP to REST.

SOAP

This is one of the possible forms of RPC (remote procedure call) architecture style. In essence, it's just a technology that allows clients call methods of server via service boundaries (network, processes, etc) as if they were calling local methods. Of course, it actually differs from calling local methods in speed, reliability and so on, but the idea is that simple.

Compared

The details like transport protocols, message formats, xsd, wsdl, etc. don't matter when comparing any form of RPC to REST. The main difference is that an RPC service reinvents bicycle by designing it's own application protocol in the RPC API with the semantics that only it knows. Therefore, all clients have to understand this protocol prior to using the service, and no generic infrastructure like caches can be built because of proprietary semantics of all requests. Furthermore, RPC APIs do not suggest what actions are allowed in the current state, this has to be derived from additional documentation. REST on the other hand implies using uniform interfaces to allow various clients to have some understanding of API semantics, and hypermedia controls (links) to highlight available options in each state. Thus, it allows for caching responses to scale services and making correct API usage easily discoverable without additional documentation.

In a way, SOAP (as any other RPC) is an attempt to tunnel through a service boundary treating the connecting media as a black box capable of transmitting messages only. REST is a decision to acknowledge that the Web is a huge distributed information system, to accept the world as is and learn to master it instead of fighting against it.

SOAP seems to be great for internal network APIs, when you control both the server and the clients, and while the interactions are not too complex. It's more natural for developers to use it. However, for a public API that is used by many independent parties, is complex and big, REST should fit better. But this last comparison is very fuzzy.

Update

My experience has unexpectedly shown REST development to be more difficult than SOAP. At least for .NET. While there are great frameworks like ASP.NET Web API, there's no tooling that would automatically generate client-side proxy. Nothing like 'Add Web Service Reference' or 'Add WCF Service Reference'. One has to write all serialization and service querying code by hand. And man, that's lots of boilerplate code. I think REST development needs something similar to WSDL and tooling implementation for each development platform. In fact, there seems to be a good ground: WADL or WSDL 2.0, but neither of the standards seems to be well-supported.

Update (Jan 2016)

Turns out there is now a wide variety of tools for REST API definition. My personal preference is currently RAML.

How Web Services work

Well, this is a too broad question, because it depends on the architecture and technology used in the specific web service. But in general, a web service is simply some application in the Web that can accept requests from clients and return responses. It's exposed to the Web, thus it's a web service, and it's typically available 24/7, that's why it's a service. Of course, it solves some problem (otherwise why would someone ever use a web service) for its clients.

TopTalkedBooks posted at August 20, 2017

The best place for you is book from Jim Webber "REST in Practice: Hypermedia and Systems Architecture"

http://www.amazon.com/REST-Practice-Hypermedia-Systems-Architecture/dp/0596805829

In book is a special chapter for that - Chapter 11 "The Web and WS-*".

When you are writting thesis about REST than this book is must have for you.

TopTalkedBooks posted at August 20, 2017

Inspect the return value, if it's not null, return some representation of it as a 200 OK response. Otherwise, return a 404 Not Found. In the end, you would have a controller like:

@RequestMapping(...)
public ResponseEntity<?> getOne(...) {
    Something something = repository.findOne(...);
    if (something == null)
        return ResponseEntity.notFound().build();

    return ResponseEntity.ok(something);
}


You can refactor the preceding code to incorporate Java 8's Optional<T>, as JB Nizet mentioned in the comments. Basically, Optional<T> is just a container that may or may not hold a value of type T. You can use this type as the return type of Spring Data JPA methods, something like the following:
public interface SomethingRepository extends CrudRepository<Something, Long> {
    Optional<Something> findById(Long id);
}

Then define one exception for 404 Not Found:

@ResponseStatus(HttpStatus.NOT_FOUND)
public class NotFoundException extends RuntimeException {}

If you throw an exception of type NotFoundException in your controllers, Spring MVC's exception resolver would catch that exception and convert it to a 404 Not Found HTTP response.

Finally your controller would be like:

@RequestMapping(...)
public Something getOne(...) {
    return repository.findById(id).orElseThrow(NotFoundException::new);
}


For more detailed discussions on:
TopTalkedBooks posted at August 20, 2017

I would recommend viewing the presentations about REST API first and find some talks on Youtube:

Most useful gems at current moment:

And don't forget Grape.

If you want to go deeper in the area, next books will help you with that:

Top Books
We collected top books from hacker news, stack overflow, Reddit, which are recommended by amazing people.