Help coderanch get a
new server
by contributing to the fundraiser

Mark Masse

author and iconoclast
+ Follow
since Nov 08, 2011
Merit badge: grant badges
For More
Cows and Likes
Total received
In last 30 days
Total given
Total received
Received in last 30 days
Total given
Given in last 30 days
Forums and Threads
Scavenger Hunt
expand Ranch Hand Scavenger Hunt
expand Greenhorn Scavenger Hunt

Recent posts by Mark Masse

Nice! Congrats guys. I really hope that you find the book helpful, but either way I would love to hear your brutally honest feedback on it. Please shoot me a quick mailto mark AT wrml DOT org. Thanks!
12 years ago

Pat Farrell wrote:

Mark Masse wrote:If the REST API designer has chosen to model "buy" using an action/controller resource that "triggered" via POST (a reasonable choice), then it is a client's job to enforce or warn about rePOSTing the "model"? ....
Clients need to understand (and account for) the nature of any HTTP methods that they use to communicate. Page 27 of my book talks a little bit more about this design concern.

I can't comment on the relative values of your approaches, but I have found that:

1) you can not trust the client software to do reasonable things. Browsers are weird, and you may not be talking to a browser.
2) If you assume that the human client has an IQ higher than a turnip, you are making a huge mistake.

I don't disagree.

Well, speaking for myself, when I write my own client apps, I know that I will at least use the HTTP methods correctly. I recommend that you all do so as well.
12 years ago
Hi Camilo,

REST is a description of how the World Wide Web works (from a software/platform perspective). The REST constraints provide high-level guidelines for Web API design. However, they leave some "wiggle room" in terms of the design of a REST API's resource model (e.g. URI paths and HTTP interactions) and its representations (e.g. JSON or XML).

The book attempts to motivate some particular choices that I believe are best practices. These include some very commonly held ideas, like the role of GET, and some not so established patterns, like hypermedia links in JSON. The book has a few code examples but it is really not an implementation guide for RESTful web services.

This book asserts that REST API designs should only be as different as they really need to be. Design differences for difference sake just makes things harder on our API clients and certainly don't help us advance toward the vision of a uniformly programmable Web. Personally, I like the idea of a World Wide Wiki - where all of the world's information is available via REST APIs that are similar enough (or provide enough metadata) that client programs can "digitally surf" (and even edit) this machine web in order to extract and mashup disparate data sets in interesting ways. Even more than that I like the idea of a open standard REST API design approach with enough inertia that we can all invest in building a set of common tools and frameworks to make programming modern web applications much easier and more fun. Lastly, I'd like us all to be able to standardize on our web application interactions without converging to a common programming language - because I don't see that happening any time soon. These ideas and goals are the motivations behind the WRML ( open source project.

Thanks for your interest,
12 years ago

Pat Farrell wrote:

Mark Masse wrote: Can you clarify what you mean by "support" for idempotency? Are you encountering many APIs that seem to "violate the contract" specified by HTTP's methods?

Yes, exactly. The classic example is a duplicate send of a "buy items in shopping cart" command, triggered by a POST. You only want the items once, not two or three times.

Ah I get your point.

One approach/perspective:
If the REST API designer has chosen to model "buy" using an action/controller resource that "triggered" via POST (a reasonable choice), then it is a client's job to enforce or warn about rePOSTing the "model"? The POST method's idempotency can not be influenced by the client or the server. HTTP allows for the POST method to have side effects, so repeat calls to the method will do whatever they do (possibly double billing a credit card). This is why the browser traps the POST form button's clicks and prompts users with "Are you sure that you want to rePOST the form data?"

Clients need to understand (and account for) the nature of any HTTP methods that they use to communicate. Page 27 of my book talks a little bit more about this design concern.

An alternative approach:
A more sophisticated REST API could choose to assign a cart ID or some other piece of state to the model that the server can check against some transaction log (in the back-end) to determine that the transaction/order has already been submitted so there is nothing to do. The API might respond with a 409 "conflict" to indicate to the client that the exact same cart cannot be repurchased.

Another approach:
The interaction could use a conditional POST, with the client adding a precondition that allows the server to verify that they are in sync (state-wise) before proceeding with the action. Page 36 of my book discusses this approach.

I am curious to hear which approach that folks like the best or if anyone has an alternative design approach that they prefer?
12 years ago
Great question. Every character in a URI, including those present in the query part, contribute to a resource's identity ( So to me this means, in the collection pagination example, that the specific collection "page" is a distinct resource whose representations may be cached individually by their unique URIs - assuming the origin API says its okay to cache then for a bit.

My mental model for a paginated collection resource is that it is literally a "Linked List" of result pages with the "next" and "previous" link relations mirroring the classic data structure's pointer-based linkages. With the primary (non-query) URI pointing to the "head" page (resource) and the page-related query parameters identifying some subsequent page (resource) in the collection.
12 years ago

Pat Farrell wrote:I find that far too many applications have no support for idempotency. Often it appears that the API designers never considered the topic.

Does the book address this?

Hi Pat,

Sorry for the delayed response - I somehow missed your post. Can you clarify what you mean by "support" for idempotency? Are you encountering many APIs that seem to "violate the contract" specified by HTTP's methods?

Here's a link for folks that aren't as familiar with the idempotent property of some of HTTP's methods:
12 years ago

Kim Baddeley wrote:Hi Mark,

What is your opinion on WADL. Should a RESTful service provide one or is the standard dead in the water?


Hi Kim,

I am a fan of the concept of making all sorts of metadata available to clients and servers that wish to "introspect" a web API's resource models and/or its data structures/schemas. While this certainly isn't a need that all clients will have but many do benefit from the kind of information that machine interfaces/contracts like WADL can provide. I have no strong bias for or against WADL, but in my crystal ball, I don't see it suddenly catching on and becoming a big part of our forward looking, client-server (REST API-oriented) web app architectures.

So, while I can relate to the ideas that inspired WADL, I am not a big fan of how it is "implemented" and I am also not sold that it adds enough value for my apps to bother with it.

If others have found it compelling and have been able to leverage it to write less boilerplate code (or whatever), I would love to hear some of those success stories.

12 years ago

John M Brown wrote:
Beyond the WRML concept (which does not have to be used to apply most all of the practices in this book), there's a lot of good information and practices contained in a concise format (as the 1st amazon reviewer admits). Much more complete than I've found in any other REST book I've read and recommended (i.e. REST in practice, RESTful service cookbook). It makes a good reference when designing a REST system beyond a sample RESTbucks application.

Thanks John. I am very happy that you've found the book helpful.
12 years ago
Hi all,

Thank you guys for the great questions.

WRML is a new open source project ( that is several months away from being ready to be useful to anyone. That said, I am very interested in feedback regarding the goals and design of WRML as an application framework.

The basic idea of WRML is that for certain kinds of apps and languages, a bit more "content type" information can be helpful to share between client and server. For other apps, this type information may not be required but it isn't harmful to communicate it (in http's common content-type header) in those cases either.

Writing a book about REST best practices means delving into representation design. O'Reilly's other REST books tend to focus on XML and Atom based representations. I knew that I wanted to illustrate data modeling in JSON but I also felt that defining or documenting our application's core types in a book or on a wiki kind of missed the point of REST and APIs in general. I wanted to view my app's types as machine readable artifacts, which is where the idea of a web resource schema came from. I then figured that in order to identify (and version) a particular data type in a web-oriented system, the schema should itself be a resource available via an API.

While it's true that many dynamic languages (like JavaScript) may not obviously benefit from having this structural type information available on the web, clients and servers written in statically typed languages (like java) can benefit greatly - to the extent of no longer needing to code the core model objects at all. The java implementation of WRML turns schemas into java interfaces (using code generation), which ultimately leads to a bunch of other interesting features, such as automated hypermedia (link) state management. I am working on coding WRML, but until I have something functional to demo, I expect and fully respect a skeptical response from everyone.

The elephant in the forum is that my book currently has a crap 1.5 star rating on amazon having only received two reviews. So, to comment on the book's current amazon reviews, I would first say that I am glad those folks read the book and seemed to find some value in it. Regarding their feedback on WRML, I think I understand where they are coming from. WRML is new. That is one strike. Today, it remains primarily as a collection of ideas and "slide ware" which don't help anyone build anything. That is strike two. Finally, it is very different from how most of us have approached web application design and implementation thus far. Major strike three.

Programmers want it to be ultra simple to get data from a web service API. Anything that seems like it wants to make this more difficult, has a funny smell and a bad taste. I can easily see how WRML might seem to offend in this way. Obviously that is neither the intent nor the plan for WRML but i don't expect folks to just take my word for that. We will build the WRML framework and then it will speak for itself. Some will like it and hopefully find it useful, while others may criticize or just ignore it.

Only time will tell if an implementation of WRML is used by anyone other than myself, but I am determined build it either way. I think it will be great (obviously) and I really want to use it to build my own stuff.

As for the book and WRML, obviously I dont think that WRML ruins the book or makes the book specific to some dead-end tech. REST (and the Web) are implementation technology agnostic, which is part of what makes it so great. I don't want to push WRML on anyone but I would be stoked if folks find it helpful once it's fully baked.

Thank you all for your interest and I hope that I can continue to look to these forums for feedback on REST API design concerns.
12 years ago

raj malhotra wrote:Hi Mark,

I dont know much about WRML.May be it is far better then my thought.But just i want to know Does your book has strong coupling with WRML? Can i learn REST full webservices with/without WRML from this book? And who is your target audience- Beginner,Intermediate or Advanced users.


Hi Raj,

WRML is new so don't feel bad for not knowing anything about it. This forum is the first place that I am really talking about it to other folks.

The book uses WRML at the end to describe some standard structures in JSON for modeling some reusable framework-level constructs, like links. For example, there is no standard way to represent a hyperlink in JSON, so WRML fills in this gap. WRML is a modeling language for a framework of ideas. As such, it also plays a part in naming the four base resource archetypes that are based, in part, by how clients interact using the core HTTP methods. By naming and modeling these design patterns as first class resource types, higher level programs, written in various languages, can begin to form around these established "second order" constraints.
12 years ago

paul nisset wrote:Thanks Mark.
The devil is in the details.

Totally. The implementation has eluded me for a long time but I think I am starting to wrangle the code-level design almost to the point where I want it.

If you are a Java guy, you might find it helpful to peek at the code itself. This class is still "very fresh", meaning a work-in-progress, but it is a central part of the Java rendition of WRML - so it will probably make sense to start here. Anyway, take a peek if you can spare the time and let me know what you think. There are some javadoc comments that will hopefully help make sense of this.
12 years ago

paul nisset wrote:Hi Mark,

How complicated is security using REST ?
Is it just a matter of passing an authenticating token in the request ?


I think the short answer is "yes."

Clients need to send opaque IDs that the API knows how to authenticate so that it can enforce an authorization policy. If a client "hasSecureStorage" it might be able to store some sort of secret password (client credentials). Otherwise the token will be exposed, so it cannot be trusted on its own. This usually means adding a time dimension, a TTL for the token, which theoretically limits the exposure if compromised. Transport Layer Security (TLS) should probably be a given for any apps that care about the security of the data or the trustworthiness of the identity represented by the client request's access token.

Architecturally, I like OAuth 2.0's idea of a centralized third party (Authorization Server) that the client and server both talk to manage some level of authentication, authorization, and client state. This helps keep each REST API node stateless (with respect to client state) and pushes that to a service that is built with a special purpose to manage it centrally (today, we might call this Facebook ).

The WRML application framework borrows this idea of leveraging a set of core REST-based services, like OAuth 2's AuthZ server, as key dependencies for the modern client-server apps. In my mind, this is true web service-oriented architecture with applications built from services that are treated like native data structures (and algorithms).
12 years ago

Max Tomlinson wrote:I meant to add that since your book doesn't mention WSO2 and that you haven't heard of them, it is helpful in giving me a view on where they might stand in the bigger scheme.
thanks again

That's a great way of looking at it. That said, I have a legitimate fear that my "tech radar" is not picking up all of the cool new REST-related and true web service stuff. It's a good problem to have though, as it seems that we are in the middle of a Web tech renaissance.
12 years ago

paul nisset wrote:Is that what your book focuses on, implementing an API for working with the constraints ?

Clarifying your model for REST would be interesting.


No problem. Together, this web page and this slide deck are an attempt to present my current mental model of REST and what it means to building modern client-server applications.

I also recently wrote an article for that talks about how the WRML media type adds a simple, universal type identifier (a schema URI) to the REST "slot" that it already belongs (the Content-Type HTTP Header). It turns out that this idea enables a whole bunch of "frameworky bits" to be invented which makes our jobs as web application programmers much easier.

I am happy to help clarify anything that you find at these links.
12 years ago
Greetings Program,

I wanted to mention that my book introduces a modeling language, called WRML (Web Resource Modeling Language, that is intended to make it easier for us to build client-server web applications that take advantage of REST APIs. I want to bring WRML to your attention for a number of reasons, but mostly I just want to share the ideas with you all and get your feedback on the architecture and design of WRML as an web application framework. The second reason is that I would like to have the opportunity to clarify and explain what WRML is and how it works - and why you might care about it. In a world of 8000+ computer programming languages and probably even more open source web application frameworks, why on earth would anyone think we need another one?

I also want a forum to debunk the idea that WRML is "like SOAP". As a colleague of mine said, "that's silly - your book is way to small for WRML to be about SOAP!". I certainly understand that WRML may look a bit foreign at first - but I think that it is new and it might have some value to anyone wanting to easily develop web apps without writing a bunch of rote, boilerplate code.

WRML is not like the other web application frameworks, or at least not like the one's that I have seen. WRML is REST-based. WRML is not tied to any single programming language or platform (other than the Web). WRML can be used to create REST APIs and their clients with "minimal" code. The WRML runtime framework itself relies on a few core REST APIs, which themselves are built using WRML. WRML takes a model-driven approach and provides GUI-based and other tools to edit the core REST API constructs like schemas, link relations, resource templates, and formats.

If any of that sounds interesting to you, I have a few references that you can look at to learn more:

  • The open source project page:
  • WRML in pictures:
  • The code for the Java implementation (so far):
  • My rough notes, written to the other committers:
  • A bunch of Proof-of-Concept proposals as decks (raw):

  • Please fire away!

    12 years ago