REST API Design Rulebook - WRML

[Mark Masse]

Greetings Program,

I wanted to mention that my book introduces a modeling language, called WRML (Web Resource Modeling Language, http://www.wrml.org) 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:

Links:

The open source project page: http://www.wrml.org/project

WRML in pictures: http://www.wrml.org/start.pdf

The code for the Java implementation (so far): https://github.com/wrml/wrml-prototype

My rough notes, written to the other committers: http://www.wrml.org/docs/notes

A bunch of Proof-of-Concept proposals as decks (raw): http://www.wrml.org/docs/decks

Please fire away!


-Mark

[raj malhotra]

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.


Thanks,
Raj

[Mark Masse]

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.


Thanks,
Raj

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.

[John M Brown]

Just wanted to add in (as I've read through the book). That most of the book's rules are good REST practices that would help the beginner and intermediate REST developers to gain some consistency. Hopefully most advanced REST programmers would already know most of these practices. There's no direct coupling or tie to WRML, though its mentioned as an option.

Hope that helps.

[Mark Tyler]

Hi Mark,

I am learning about and working with REST on my current job assignment, so your book looks like a good resource for me to check out. When I went to Amazon.com to get more information about the book I was discouraged by the only two reviews. Both reviewers seem to be violently opposed to your insertion of WRML into your REST presentation. I am curious why these reviewers would be so opposed to something you say was "intended to make it easier for us to build client-server web applications that take advantage of REST APIs." How do you respond to their criticisms?

Thanks,
Mark

[Will Hartung]

Mark Masse wrote:
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.

I've looked over the wrml.org site, and the slide decks you've posted, etc. I didn't study them in particular detail, but all I saw was some references to some workflows and tools and frameworks.

I haven't seen any examples of anything looking like a modeling language.

There's mention of schemas and formats, but those aren't in regards to WRML itself.

There's the application/wrml media-type, but that appears to not be a media-type (at least as generally understood), but rather a mechanism to link the schemas and formats together.

The RFC draft on the website is "working on it, come back later" message.

So, do you have some examples of the WRML, or other documentation, besides the book that we can see?

[Mark Masse]

Hi all,

Thank you guys for the great questions.

WRML is a new open source project (https://github.com/wrml/wrml-prototype) 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.