Tim Strehle’s Blog » HTML Hypermedia API resources. Ruben Verborgh. Etheses.dur.ac.uk/4843/1/4843_2312.PDF. HATEOAS. 2011 | Second International Workshop on RESTful Design at WWW 2011, 28 March 2011, Hyderabad, India. RESTful Enterprise Development. REST Media type explosion. REST API Design: Invent Media Types, Not Protocols and Understand the Importance of Hyperlinks. Early this week, Roy Fieldings wrote a post entitled REST APIs must be hypertext-driven where he criticized the SocialSite REST API (a derivative of the OpenSocial REST API) for violating some constraints of the Representational State Transfer architectural style (aka REST).
Roy's key criticisms were API designers, please note the following rules before calling your creation a REST API: … … A REST API should spend almost all of its descriptive effort in defining the media type(s) used for representing resources and driving application state, or in defining extended relation names and/or hypertext-enabled mark-up for existing standard media types.
Any effort spent describing what methods to use on what URIs of interest should be entirely defined within the scope of the processing rules for a media type (and, in most cases, already defined by existing media types). [Failure here implies that out-of-band information is driving interaction instead of hypertext.] Explaining REST and Hypertext: Spam-E the Spam Cleaning Robot « Lost Boy. Www.markbaker.ca/2001/09/draft-baker-http-resource-state-model-01.txt. A Hypermedia API Reading List. 11 February 2011 Originally, this post was titled "A RESTful Reading List," but please note that REST is over. Hypermedia API is the new nomenclature. I've been doing an intense amount of research on Hypermedia APIs over the last few months, and while I didn't save every resource I found, I've made a list here of the most important. I'll be updating this post as I get new resources, so check back! The book list If you want to go from 'nothing to everything,' you can do it by reading just a few books, actually.
Start off with Restful Web Services by Leonard Richardson and Sam Ruby. It also comes in cookbook form . Next up, read REST in Practice: Hypermedia and Systems Architecture . To really start to truly think in Hypermedia, though, you must read Building Hypermedia APIs with HTML5 and Node . [HTML5, Node.js, and CouchDB] are used as tools illustrating points about hypermedia design and implementation. This is not a Node.js book. And, in the afterward: Yes, it still has REST in the title. Steve.vinoski.net/pdf/IEEE-REST_Eye_for_the_SOA_Guy.pdf. Applying the Web to Enterprise IT. User Jan Algermissen. Www.prescod.net/rest/ Restful Objects | A hypermedia API for domain object models.
Designing a Secure REST (Web) API without OAuth. Situation You want to develop a RESTful web API for developers that is secure to use, but doesn’t require the complexity of OAuth and takes a simple “pass the credentials in the query” approach… or something equally-as-easy for people to use, but it needs to be secure. You are a smart guy, so you start to think… Problem You realize that literally passing the credentials over HTTP leaves that data open to being sniffed in plain-text; After the Gawker incident, you realize that plain-text or weakly-hashed anything is usually a bad idea. You realize that hashing the password and sending the hash over the wire in lieu of the plain-text password still gives people sniffing at least the username for the account and a hash of the password that could (in a disturbing number of cases) be looked up in a Rainbow Table.
That’s not good, so you scratch your head some more… “Still not quite right!” Solution So you keep searching for articles on “secure API design“… That seems pretty straight forward. Modeling operations in REST « Bill the Plumber. A Red Hat Colleague of mine, Bryan Kearney, recently solicited my advice about a RESTful interface his team was creating for an entitlement system being used for our products. Here’s what he wrote to me: The project is called Candlepin, and it is an entitlement engine.
You can see it at and the code at We are using RESTEasy as the engine, and I would say our API is at gen 2. We are no longer doing too much RPC style calls.. but are not yet doing a HATEOAS API.Our current quandry is around how to model state trnasitions on resources. We had a bit of an email exchange, but here’s the advice I gave him summarized. Have your clients consume links, not a URI scheme Modelling URI schemes is an implementation detail. BUT, URIs are an implementation detail of your restful web services. Location Transparency. Avoid changing the meaning of an HTTP verb: specifically DELETE Use links to model operations (Approach 3)
S blog: Linking in JSON. Friday, 25 November 2011 To be a full-fledged format on the Web, you need to support links -- something sorely missing in JSON, which many have noticed lately. In fact, too many; everybody seems to be piling on with their own take on how a link should look in JSON. Rather than adding to the pile (just yet), I thought I'd look around a bit first. What am I looking for? Primarily, a way to serialise typed links (as defined by RFC5988, "Web Linking") into JSON, just like they can be into Atom, HTTP headers and (depending on the HTML5 WG's mood today), HTML. 5988 isn't perfect by any stretch (primarily because it was an after-the-fact compromise), but it does sketch out a path for typed links to become a first-class, format-independent part of the Web -- as they well should be, since URIs are the most important leg holding up the Web. My immediate use case is being able to generically pull links out of JSON documents so that I can "walk" an HTTP API, as alluded to previously.
JSON Reference. REST-ful URI design | RedRata. This post is about URI naming. Designing URI names. Some tips and rules and conventions that you can follow when figuring out your application’s URIs. The focus is on URIs for ‘REST-ful’ applications. But many of the tips apply to any kind of website or application. REST-ful URIs and non-REST-ful URIs A REST-ful URI is a URI that identifies a domain resource (like a book or a shelf or a book loan in a library application) rather than an application resource (like a web page or a form in your application or website). Typically ‘REST-ful’ URIs are for APIs. Non-REST-ful URIs are more likely to identify application resources like web pages rather than domain resources: /admin/updatebook.jsp?
PS: There can be confusion about URIs and URLs (and URNs!). “URIs do not matter with REST-ful applications” This is what some people say. With REST-ful applications the first thing you need to do is to identify the resources you are representing in your system. What are the criteria for a good REST-ful URI? Identifying Application State.
Abstract As the Web has evolved from a Web of documents to a Web of applications, the use of the hash sign, #, in URIs has evolved correspondingly. Originally introduced as a static "fragment identifier" to identify locations in a document, it is now being used in many more complex ways, for example, by SVG and PDF to select from and render documents and as arguments to Web applications that are interpreted by JavaScript. Fragment identifiers are used to provide several different kinds of parameters to the client-side application, such as the actual URI of a video to be played to a video player, or the position and zoom to a map. Unlike query parameters preceded by ? This document explores the issues that arise from these new uses of fragment identifiers and attempts to define best practices. 1 Introduction [RFC 3986] defines the character string following the ?
This document explores the issues that arise in this context, and attempts to define best practices that help: 2.5 Other Examples. Measuring REST. Kennethlove/Banana-Py - GitHub. HAL - Hypertext Application Language. A lean hypermedia type Author: Mike Kelly <mike@stateless.co>Created: 2011-06-13Updated: 2013-09-18 (Updated) Summary HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API. Adopting HAL will make your API explorable, and its documentation easily discoverable from within the API itself. In short, it will make your API easier to work with and therefore more attractive to client developers.
APIs that adopt HAL can be easily served and consumed using open source libraries available for most major programming languages. About The Author Mike Kelly is a software engineer from the UK. Quick links General Description HAL provides a set of conventions for expressing hyperlinks in either JSON or XML. The rest of a HAL document is just plain old JSON or XML. HAL is a little bit like HTML for machines, in that it is generic and designed to drive many different types of application via hyperlinks.
Having said that, HAL is actually very human-friendly too.