"REST enables intermediate processing by constraining messages to be self-descriptive: interaction is stateless between requests, standard methods and media types are used to indicate semantics and exchange information, and responses explicitly indicate cacheability." (Fielding, 2000)    (5UA)

There are many lessons along the way to a RESTful system. These are only a few, from the perspective of BenjaminCarlyle.    (5U2)

Benjamin has worked at translating commercial software to a REST model, and developing frameworks for the support of new REST software. His work is proprietary, but his lessons are not. These are the steps he has taken.    (5U3)

Lesson 1: Everything is a Resource. Everything gets a URL.    (5U4)

The first step in transforming any large software system to REST is normalising the identification of resources. Chances are there are a few schemes floating around in your software already. In constrained footprint environments the identifier could be a simple as a pointer or a memory offset. You may be using a combination of several strings to identify a resource. The goal is to normalise on just one identifier scheme that works for everyone. Unless there is a good reason for alternatives, use URLs. Forget about URIs that are not URLs for the moment. REST is about resources that can be located, even if you haven't gotten around to putting a useful resource at the end of the URL yet.    (5U5)

If you speak unusual protocols, you may have to make up some URL schemes. Use standard schemes for standard protocols. Consider joining a standardisation effort where your protocol is non-proprietary, or widely understood. If you haven't settled on a protocol yet, use HTTP as much as you can. If your environment is too constrained for HTTP, design your protocol with a migration path to HTTP.    (5U6)

Practical Steps    (5U7)

Immediate benefits    (5UE)

Resources    (5UI)

Lesson 2: The uniform interface    (5UL)

Now that you can identify everything with a URL, you should be ready to access everything as a resource. HTTP is a template for this. If you can use HTTP to access all of your objects, there is probably nothing more you need to do. If you speak multiple protocols, consider introducing a layer that provides a protocol-independent view of a resource. Provide implementations for each scheme you came up with in Lesson 1.    (5UM)

The uniform interface decouples any particular piece of software from knowing exactly how it is accessing a particular resource. This allows hyperlinks to be followed to any resource over any supported protocol without prejudice as to which is which.    (5UN)

Incorporate all of the features you expect protocols to have into this abstraction. For me that meant pretty much an exact replica of a HTTP resource, plus additional support for subscription. It is important that as well as support for traditional REST methods like GET you allow for custom methods. Your software won't transition to REST in a day, and you will need a way to access these additional functions.    (5UO)

Don't worry about the inefficiency of the string handling you are doing. Profile it, and if it really isn't performing and can't be made to perform in particular cases you should provide a shortcut through this layer. Over time the number of pieces of your system that need these performance-driven special cases will fall and eventually pale into insignificance.    (5UP)

Practical Steps    (5UQ)

Immediate Benefits    (5V3)

Resources    (5V5)

Lesson 3: RESTful design with constrained methods    (5V7)

Fielding's thesis doesn't state which methods should be used in REST, only that they should be standard methods. He gives us a hint, though, in the use of the words "State Transfer" in his title. I add support for subscription to the set of methods that I consider standard, but I'll skip that for the purpose of this tutorial.    (5V8)

The only valid state transfer methods are:    (5V9)

GET transfers a representation of the state of a resource from the server to the client.    (5VE)

PUT transfers a representation of the state of a resource from the client to the server.    (5VF)

POST transfers a representation of the state of a new resource from the client to the server. The server's response includes the location of the created resource.    (5VG)

DELETE transfers the "deleted" state to a resource.    (5VH)

Any other interpretation of these methods is tunneling. Using POST to transmit form data can be RESTful, but is often not. Using POST to transmit arbitrary method invocations either by encoding the method name in the body or in the URL is tunneling.    (5VI)

Starting from these definitions you can start to do RESTful design.    (5VJ)

RESTful design consists of two views of your URL-space. The first is the list of URLs your applications provide. The second is a navigation map from resource to resource.    (5VK)

The URL List    (5WW)

You should be able to list and describe the schema of information you expect to find at each URL. At a train resource you can expect to find information about that train. At a bank account resource you can expect to find information about the bank account.    (5VL)

Think about what a GET, PUT, POST, and DELETE would naturally do to these resources and which methods should be allowed. If you find yourself in a quandary as to whether POST should do one thing or another, you don't have enough resources. Make your resources as obvious and well-defined as possible. You should be think of real-world objects, or real concepts as much as possible. REST design is what object-oriented design should have been.    (5VM)

Navigation Map    (5WX)

Your navigation map is just as important as your URL list. REST incorporates its discovery mechanism as part of the content. The body received in a GET request to one resource should lead to another resource. The Location header in a response from a POST request allows navigation to new resources. A client always navigates from a particular starting point on to other resources. Your map should show both starting URLs that you expect users or clients to know or have configured into their system, and the links from these resources to other resources.    (5VN)

List out the resources in a block form. Show arrows pointing into the starting resources. Now, draw the links from these resources to other related resources. If you find it is taking too many steps to get from one place to another, consider putting direct links into your content. If that is too difficult, consider inserting resources that act as discovery points or "search engines". They should return a form that the client application can fill out to find specific resources.    (5VO)

Content    (5WY)

Out of this process of developing your lists of URLs and your navigation map, schemas for each resource should develop. Thinking simply about methods forces you to put some extra work into defining content types, and this can mean that the complexity is transferred to the content. This is a good thing. The next lesson will address content types head on, but that is the hardest lesson of all.    (5VP)

Practical Steps    (5VQ)

Immediate Benefits    (5VT)

Resources    (5WM)

Lesson 4: Normalising your content types    (5W0)

In Lesson 3 we learned that we should not allow variation in methods, and should move all of our complexity and variation into our content types. In Lesson 4 we learn that we should not have any variation in content types.    (5W1)

Variation in content types is easier to deal with than variation in methods. It is possible for a resource to deal with various content types both for input and output, so it is possible to support a spectrum of content types from the very proprietary to the very generic. However, the more proprietary content types you depend on the less your software will inter operate with itself and with other software.    (5W2)

The bottom line is this: When you introduce a new content type, your service and your clients both need to write code to support it. In the absolute limit of REST there is no need to write new client software to support new services. All content types are understood by everyone. Whenever you can draw a boundary within which your content types are understood, you are drawing a boundary within which network effects can be achieved using the content type. Network effects obviously have a greater effect when the network is large.    (5W3)

The classic content type for text is HTML, and you should follow its lead in defining your own content types. Use a text-based syntax such as XML. This allows you to ignore content in messages you receive that you don't understand, and to add additional content to more standard types where they are not an exact match to your needs. I'll say that namespaces actively work against the useful development of an XML or other text format and leave it at that. If you want to know more, bug me for another article or to point you at existing work.    (5W4)

After you have defined your straw man format you should be going into a research phase. Look for formats that are close to what you need. Even if they aren't an exact match, see if you can bend them or use some ideas or names from them. The closer to some existing standard you can get, the greater the chance of eventual standardisation. Your goal is that every important format you use is or becomes a global standard.    (5W5)

Moving to a standard identification model, to a standard resource abstraction layer, and to a standard meaning for the REST verbs are all relatively easy. They are technical rather than social problems to solve. Standardising content types is hard for non-technical reasons. This lesson is last because it is the hardest to implement, and because you will get a lot of benefits along the way even when you don't achieve this final stopping point along the way to REST nirvana. If you do or can achieve it, celebrate. You've won the war.    (5W6)

Practical Steps    (5W7)

Immediate Benefits    (5WI)

Resources    (5WN)