A few weeks back, I attended my first RESTFest “unconfernece””. This was a really great event put on by some fantastic folks. The “everyone talks” aspect of RESTFest is actually awesome idea for a conference this size. This format is great because if you’re like me, you had some things you wanted to get some feedback on and this provides the forum to do just that. Everyone gets a chance to do a quick 5-in-5 talk about anything. I was looking to get some feedback on some ideas I’ve been considering about push notifications in Web APIs.

I titled my talk “Real-Time Web APIs,” but I’m no so much interested in Web APIs that follow “real-time computing” constrains. Really, I’m looking to see if there’s a good way to describe a service that streams push notifications from a Web API that follows “RESTful” architectural constraints. There’s a lot of good ideas out there, but many of them either assume that the client either a web browser or running an HTTP server. Additionally, the mechanism to describe these services need some work.

The Goal

The core building blocks for push notifications are already available, but not so much the means that aid in discovery and the description of such resources. I’d like to be able to organize these pieces so that the following requirements can be met:

  1. Don’t assume that the subscriber is able to receive a callback using HTTP POST. If the subscriber is a web browser or a thick desktop client like a Swing or JavaFX application (yes, people still make these!), or even a nativ app on iOS, running a web server to receive and HTTP callback isn’t always practical or feasible.
  2. Advertise that a given link is exposing a stream of events via a link relation. This might be similar to the monitor link relation, but not necessarily bound to SIP.
  3. The link relation should be able to indicate the media type that event messages are described in, ideally via the type property.
  4. If there’s a sub protocol involved, it should also advertise what sub-protocol. If event stream is a media type that supports embedded content, it should also express that as well.
  5. Subscribing to a stream or feed should be simple

WebSockets and HTM5 Server-Sent Events (SSE) present some interesting opportunities for Web APIs that demand low-latency push notifications while also removing the need for a consumer to run an HTTP server. Keep in mind that I’m not talking about doing something like “REST over WebSockets (Shay does make some great points though!),” I’m simply looking for push notifications without the need for for the consumer to run a web server as well as describing the stream via link relations. I think it could be done, but there’s some missing bits.

PubSubHubub

PubSubHubub ticks a lot of check boxes for me, such as:

  • While the protocol is built around Atom and Atom concepts, it could support a variety of media types. It’s using the Content-Type header to express what is coming over the wire.
  • It sports a discovery model using the rel="hub" link relation either in a link header or a link within an Atom feed.
  • The subscriber subscribes to the Topic URL from the Topic URL’s declared Hub(s) using the PubSubHubbub subscription protocol.
  • Publishers ping the “Hub” to notify it of updates, aggregates the content, and sends it to the subscriber using an HTTP POST request to the call hub.callback URL.

What I like about it a lot is the use of hypermedia to do discovery and call backs. Additionally, it’s using standards means to describe what’s coming over the wire. The rel="hub" link relation combined with the script ion protocol is super easy an fit works. My challenge with PubSubHubub is the requirement of an HTTP callback on the part of the subscriber. As stated earlier, this isn’t always possible.

From my perspective, PubSubHubub has the right foundational model. It’s simply HTTP callbacks that are the sticking point. So can we do something similar with WebSockets or Server-Sent Events? I think so, but there’s some challenges with existing formats in order to make this work.

Server-Sent Events

I REALLY like HTML5 Server-Sent Events (SSE). A lot. I’m also really annoyed by the fact that Internet Explorer still isn’t supporting SSE in IE11. What I like about SSE is that it’s a media type (text/event-stream) so the subscriber will know that this URL represents an event stream. The event stream model is also dead simple:

event: change
data: 73857293

But it could be also like this:

event: change
data: {"@id" : "15628", "@type" : "ChangeEvent",  "value" : "73857293" }

Or even this:

event: change
data: {
data: "@id" : "15628", 
data: "@type" : "ChangeEvent",  
data: "value" : "73857293" 
data: }

Or like this (If you’re into this sort of thing):

event: change
data: <ChangeEvent><id>15628</id><value>73857293</value></ChangeEvent>

As you can see, the data field could contain nested media type like XML, JSON, or something else. The problem is that that there is no way to indicate that. How does one know that the data field contains structured content such as JSON? The browser gets around the issue by embedding JavaScript in an HTML document that references the stream:

var source = new EventSource(’/updates');
source.addEventListener('add',  changeHandler, false);

Obviously, the changeHandler function will parse and handle the embedded content. This works great where the subscriber is a web browser (or embedded browser), but for other environments it’s not so easy.

We could express this via a link, but it’d be missing some details. Let’s assume we have a link relation called stream that informs a client that this link represents a stream of events:

Link: <http://example.com/events>; rel="stream"; 
      type="text/event-stream";

It works and declares that the link is a stream of event and it exposes the events via SSE. But the subscriber has no hints that the data field contains JSON or XML content. In cases where the browser, or an embedded web browser, are not available, how does can a client get more information as to process a stream? For SSE, one option might be to include a media type parameter, call it data if you will, that would indicate that the nested type is something like JSON-LD:

Link: <http://example.com/events>; rel="stream"; 
      type="text/event-stream;data='application/ld+json'"

It’s just an idea, but it could be workable. I would love feedback on this and would REALLY like to see Microsoft add Server-Sent Events to IE at some point.

WebSockets

WebSockets are neat, but the majority of use cases for streaming notifications only really needs to go one way. The bi-directional nature of the WebSockets protocol is a nice to have but not entirely necessary for most applications. WebSockets by itself really isn’t that useful. A number of WebSocket examples you’ll see are effectively someone’s home-grown, JSON-based, socket protocol. It’s a bit too cowboy for my tastes, but it can get the job done.

Where I do find WebSockets more useful is being able to leverage a well-defined subprotocol over a WebSocket. At the moment, I’m quite of fond of STOMP, particularly STOMP over WebSockets. In a Java shop that is already heavily invested in JMS, STOMP over WebSockets is a reasonable leap given that tools such as ActiveMQ, RabbitMQ, and others are support STOMP over WebSockets now.

Building on the Server-Sent Event examples earlier, we have some similar problems such as:

  • We still don’t have a good way to indicating what might be coming over the wire
  • We have a new problem since we’re dealing with another protocol that supports subprotocols, we don’t have a means to identify the sub-protocol that the WebSocket will be using

At RESTFest, I crapped up a variation of link relation like so:

Link: <wss://example.com/events>;rel=”stream/v12.stomp";
       type=“application/ld+json";

Here, we’d overload the rel field to indicate that it’s a stream but that it’s also using STOMP as the sub-protocol, specifically STOMP v1.2 (note I’m using IANA WebSocket subprotocol IDs here). Because the URI begins with wss://, we know that we’re using WebSockets over SSL. The type property is indicating that the messages will be using application/ld+json. The problem with both approaches is that if I want to offer another alternate message formats (say JSON-LD or XML), then this solution does really work. But maybe that’s not a problem.

Constrained Application Protocol

One of the great things about attending a workshop like RESTFest is that you’re surrounded by people who are smarter or more experienced than you. After my 5-in-5, Mike Amudsen had a few good questions about what I was trying to do. He then asked if I had considered CoAP, or the Constrained Application Protocol. Having never heard of CoAP, I obviously hadn’t taken it into consideration. CoAP more than likely satisfies a number of my needs. Since it’s still in draft form, it’s not an easy sell yet. Without a doubt, CoAP is something to keep an eye one.

Wrapping Up

Right now, I’m going down the STOMP over WebSockets route. I’d REALLY prefer Server-Sent Events, but the fact that Microsoft isn’t supporting SSE in IE10 and IE11 is AND the corporate standard in most shops, it sadly makes SSE a non-starter. In the coming weeks, I’ll be slapping some code up on GitHub to test out some ideas. I’d love to get feedback on these ideas to see if I’m going off the rails or if these ideas have some merit.

After a months of not blogging and kind of working on my URI Template library, I finally managed to get out version 2.0.1. The new API makes a quite a bit of changes and it does break some things in version 1.x. Here’s a run down of what has changed:

  • Better error handling. The API can now be more specific about what the error was and more importantly, where it was.
  • The code was refractored to support and internal model, which will help support reverse matching.
  • A new UriTemplateBuilder API for programatically creating URI templates
  • Support for Jackson serializer/deserializers

Overall, it’s cleaner and easier on the eyes. Now to wrap up reverse matching.

Over the past few days I have been reading up on the State Chart XML spec. Ever since reading some of Stu Charltons ideas on a RESTful Hypermedia Agent and listening to his WS-REST keynote presentation, I’ve taken more of an interest in hierarchical state machines and began taking a more in-depth look into SCXML.

The design of SCXML is interesting. I like the ECMA Script functionality and XML structure feels clean at first. It all seems fine until you get to the section on executable content. There’s a bit of debate around “executable xml” and executable XML frameworks like Jelly. And even folks poking fun at the idea of an XML programming language. As a Java guy, I have grown to dislike build tools such as Ant due to the fact that one can express relatively complex conditional logic in XML. I like tools like Maven better since it’s XML model is more declarative rather than executable (profiles are conditional). When I need more complex build operations, I’d be looking at tools like Gradle. Don’t get me started on XSLT.

I really like the concept of SCXML, but I’m not sold on the design. I don’t really have issue with the use of XML in general, I get it. However, the executable XML content bit is really hard to get past. Expecially when a scripting evironment is available to the SCXML environment. I can debug JavaScript code with a number of tools. Executable XML content? Not so much. For me, the executable content bit is the technical equivalent of a two-bagger.

After a few weeks of tweaking, I put out a new release of Handy URI Templates. What’s important about version 1.1.2 is that it is now being tested against the uritemplate-test suite started by Mark Nottingham. Most importantly, it is also now passing all tests. Additionally, this release also marks the introduction of expression validation as well. If you’ve been using the 1.0.x versions, I’d highly recommend moving up to 1.1.2.

URI Templates can make interacting with the web APIs like the Facebook Graph API a little easier. Here, I’ll show you how you can use URI Templates to create request URIs into the Facebook Graph API using the Handy URI Templates library. The URI Template examples described should be usable by any RFC6570 URI Template processor, but I’ll be focusing on how to use the Handy URI Templates API in Java. If you’re using PHP, have a look at Michael Dowling’s excellent Guzzle Framework which has great URI template support.

URI Template Basics

We’ll assume you have some familiarity with URI templates. Basically, a URI template is expression where replacement variables are identified by the text between ‘{‘ and ‘}’, like so:

https://graph.facebook.com/{id}

Where {id} is the name of the variable. This is similar to how paths are expressed in JAX-RS, and OpenSearch URL template syntax . The RFC6570 spec provides a lot more details on the URI template standard syntax, so we’ll focus on how to use URI templates in conjunction with the Facebook Graph API.

Facebook Graph API Basics

For the most part, most URIs in the Graph API follow the basic pattern of hostname + id. In a URI template, this pattern can be expresed as:

https://graph.facebook.com/{id}

When the template variable is expanded, it will allow you to create URIs that can be used request resources like so:

  • Users: https://graph.facebook.com/btaylor (Bret Taylor)
  • Pages: https://graph.facebook.com/cocacola (Coca-Cola page)
  • Events: https://graph.facebook.com/251906384206 (Facebook Developer Garage Austin)

And so on. Facebook also requires you to supply the access_token in a query parameter on the request URI, so now we end up with the expression:

https://graph.facebook.com/{id}{?access_token}

Please check the Facebook documenation on how to get the token.

Using the Handy URI Templates API, you can create a URI from an expression like so:

String expression = "https://graph.facebook.com/{id}{?access_token}";
String uri  = 
   UriTemplate.fromExpression(expression)
              .set("id", "bgolub")
              .set("access_token", System.getProperty("fb.access_token"))
              .expand();

This will give you the following URI:

https://graph.facebook.com/bgolub?access_token=your_fb_access_token

Because the {id} variable can contain sub paths, we need a way to express that. If we have want to express a URI template that gets a users information or the users photo albums, we need additional path segements. We could use multiple path segments with more variables, but this can make the template more complicated. One option is to modify the expression so that {id} can accomodate a single path segement or multiple path segments by rewriting the expression as:

https://graph.facebook.com{/id*}{?access_token}

This does a few things:

  • By putting the path ‘/’ operator in the variable expression, we’re stating that the values in this variable path segements. By default, if the variable values is an array, Collection or Map, the values will be ‘,’ delimited.
  • The * modifier means ‘explode’. With an array or Collection plus the explode modifier, the values will be delimited by the ‘/’ operator.

Now if we change the code a little bit:

String expression = "https://graph.facebook.com{/id*}{?access_token}";
String uri =  
    UriTemplate.fromExpression(expression)
               .set("id", new String[] {"bgolub","albums"})
               .set("access_token", System.getProperty("fb.access_token"))
               .expand();

You’ll note that the value we pass to the id variable is an array of strings and the processor will render valuse as two strings separated by a /.The resulting URI is now:

https://graph.facebook.com/bgolub/albums?access_token=your_fb_access_token

Now lets see how we can make more advanced types of requests.

More Advanced Requests

The Graph API has a number of query parameters that modifiy the request. All of these are defined in the Facebook Graph API documenation so I won’t detail them here. With all of the query parameters collected, you end up with the following URI template expression:

https://graph.facebook.com{/id*}{?q,ids,fields,type,center,distance,limit,offset,until,since,access_token}

You can pretty much use this template express for the majority, if not all, of the Facebook Graph API. We’ll use that expression for rest of the examples.

Search Request URIs

With the URI template, we can create URIs that map to Graph API search requests. Using the “coffe” example from the Facebook documenation:

String expression = "https://graph.facebook.com{/id*}{?q,ids,fields,type,center,distance,limit,offset,until,since,access_token}";

String uri = 
    UriTemplate.fromExpression(expression)
                .set("id","search")
                .set("q", "coffee")
                .set("type","place")
                .set("center", new float[] {37.76f,-122.427f})
                .set("distance", 1000)
                .set("limit", 5)
                .set("offset", 10)
                .set("access_token", System.getProperty("fb.access_token"))
                .expand();

This will give us the URI:

https://graph.facebook.com/search?q=coffee&type=place&center=37.76,-122.427&distance=1000&limit=5&offset=10&access_token=your_access_token

Note how the variables until and since are not included in the expanded URI.

FQL Request URIs

Even things URIs with FQL queries can be expressed in a template. Give our code:

String expression = "https://graph.facebook.com{/id*}{?q,ids,fields,type,center,distance,limit,offset,until,since,access_token}";

  String uri = 
    UriTemplate.fromExpression(expression)
               .set("id","fql")
               .set("q", "SELECT uid2 FROM friend WHERE uid1=me()")
               .set("access_token", System.getProperty("fb.access_token"))
               .expand();

Wrap Up

Hopefully this gives you a good idea on both how to use URI Templates in general, and a good insight into how you can use teh Handy URI Templates API. If you want more exmaples, have a look at the code on GitHub here. There are examples for Facebook, Twitter, and GitHub.

In my copious spare time, I have managed to cobble together an initial implementation of the URI Templates spec (RFC6570),  for Java. The project is up on GitHub here:

http://github.com/damnhandy/Handy-URI-Templates

The majority of the documentation is available in the README file, so have a gander at that for details on how to use it. It’s in the initial phases right now, but it’s a good time to kick the tires and provide feedback.

 

It often pains me to hear people talking about  so-called “RESTful URLs”. If you’re using that term, or your spending the majority of you application planning designing URI structures rather than your media types, then chances are you don’t really get the concepts in REST.

Frequently, I see developers sit down and start doodling a “REST API” by mapping out a bunch of URI templates like so:

/users/{userId}

/users/{userId}/stuff

/users/{userId}/stuff/{stuffId}

I’ll admit that I’ve been guilty of taking this approach myself. For one thing, it’s easy to communicate on paper. Most folks in business roles are used to seeing site maps where the content layout and URL structure are usually one in the same. By laying URI templates, you’ve kind of accomplished the same thing. Folks can visualize a high-level structure of your application, but you end up backing yourself into a corner that is difficult to get out of. Stu Charlton perhaps summed it up best in one of his more insightful posts:

If one is thinking of “how to methods map to my URI structures”, we’ve basically lost the plot as to why we have HTTP, URIs and media types in the first place. The goal is to *eliminate* the API as we normally think of it. (It’s not about a library of calls over a network).

The problem is that in approaching application design with the URI structure first is that you’re doing things bassackwards. Some people do this because they’ve followed some debatable advice and identified all of the “nouns” their application and started to work out a series of URL patterns that map to these nouns. As they create these URLs, they’ve followed some questionable advice as to what constitutes a “RESTful URL.” Subbu has another nice post dispelling some of those claims, so I won’t get into it here. The problem with doing all of the URI structure work up front is that you end up create a set of type resource URLs end up becoming fixed. Clients now end up coding to a specific set of URI patterns and/or conventions that are only discoverable from your documentation. The URI says nothing about what the data looks like or how the client should interpret it.

Imagine for a moment that you’re a DBA and you’re designing a set of database tables. Which of the two activities are you likely to spend more time on:

  1. The structure of your primary keys
  2. The schema of your database tables

A few of us would opt for something like MySQL’s auto-increment function and we’d be spending the majority of our time on describing the schema. In designing a RESTful application, you should be focusing on the design of your media types rather than what your URLs look like. To be more blunt: you must be focusing your efforts on what the hell your data looks like to consumers of your application. In addition to that, you need to think about how you are expressing links to other resources within your application or resources that are external to it.

This isn’t to say that URL design should be arbitrary and delegated to your web framework of choice. Of course not, you should still have URI strategy. The point is that the specific URI structures are not what consumers of your API will have to deal with directly. It is bad form to make a client rely on “out-of-band” information to construct a URI in your own special little way in order to get into your application. Take this blog post for example. You likely followed a link posted somewhere else. It could have been from an Atom feed, a search result in Google, or a Bit.ly link off of Twitter. It is highly unlikely that you had to type in the URL yourself and figured out the WordPress permalink structure that I have enabled on this site. If you did do that, well then, you’re awesome!

The fact is that clients will enter your application from some entry point or bookmark you’ve defined (.well-known is looking promising), or somewhere else on the web. Unless you’re a major player like Amazon, Facebook, or others, these clients won’t know that you have documentation that painfully detail your APIs URI structures. These clients will simply follow a link into your application. They didn’t type it in according to your fancy-schmancy URI template scheme that is only found in your documentation.  The URL is only a means to identify an locate a resource on the web, it does not define how the resource is represented or make suggestions as to what it’s about (remember that URIs are opaque?). At the end of the day, the client is going to have to be able to understand the media type that is retuned by requests made that URI. If you spend all of your time up front mapping methods to URI structures, you’ll end up introducing a coupling that you can’t easily break free from.

A year has passsed since my last post on URIs and URLs and it would seem that some of the concepts are still lost on some folks. With that said, I figured I’d throw up another post that I could try and address some of the questions raised in the comments of both posts.

URLs and URNs are both URIs

This is one point that can’t be stated enough. A URL is a URI and a URN is a URI, plain and simple. It’s really quite challenging to phrase it any other way. It’s like trying to explain that a Human is a Mammal but a Mammal is not always a Human.

Examples of URLs and URNs:

People have also suggested that these posts could have been more helpful if I had provided some examples that illustrate the difference between a URL and a URI. Based on the previous point, one should able conclude that a URL is a URI and therefore there’s no reasonable way to present an example that distingushes the two. However, we can provide examples that distingush a URL from a URN:

All of these Examples are URIs:
Examples of URLs: mailto:someone@example.com
http://www.damnhandy.com/
https://github.com/afs/TDB-BDB.git
file:///home/someuser/somefile.txt
Examples of URNs: urn:mpeg:mpeg7:schema:2001urn:isbn:0451450523
urn:sha1:YNCKHTQCWBTRNJIV4WNAE52SJUQCZO5C
urn:uuid:6e8bc430-9c3a-11d9-9669-0800200c9a66

Again, all of the examples above are all valid examples of URIs. You’ll note of course that all of the URNs are prefixed with “urn:”.
URIs are Opaque Identifiers

There’s a very informative page by Tim Berners-Lee that provides a lot of good deails on Uniform Resource Identifiers. One very important point is the notion of URI opacity, which states:

“The only thing you can use an identifier for is to refer to an object. When you are not dereferencing, you should not look at the contents of the URI string to gain other information.”

When you followed the link to this page, you didn’t have to do anything other than clicking it. Your browser only had to look at the URI scheme and the domain in order to resolve this particular document. Everything after “damnhandy.com” is defined to be opaque to the client. This point may seem orthogonal to the original post, but it’s a very important aspect of URIs. I bring this point up because the following question was asked in the comments:

Can we say that:

“http://www.domain.tld/somepath/file.php?mykey=somevalue”

is an URI

and that the “http://www.domain.tld/somepath/file.php” part is an URL?

No. No you cannot. Both are URLs, which are also URIs. The idea behind URI Opacity is that you should not look at the string to make any inferences as to what is at the other end. The presence of a query string does not distinguish a URL from a URI. Both strings are URIs and URLs.

Another commenter also asserted the following:

URI is whole address of a resource but resource extension is not mentioned. in URL we also mention the extension.
for example:

URI: www.abc/home
URL: www.abc/home.html

This is also incorrect. Being pedantic, neither is a syntactically correct URI or URL. But that aside, the presence of a file extention also does not distinguish a URI from a URL. Again, they are both valid URLs as well as URIs. Going back to URI opacity, you also cannot conclude that the two URLs reference the same resource or the same representation. The URI is an opaque string that identifies a resource. They’re still both URIs.

HTTP URIs Can Identify Non-Document Resources

This the one point that I think hits at the crux of everyone’s confusion on the matter. Things get all meta-meta when we start using URIs to identify things that are not documents on the web. It is perfectly acceptable to use to URIs to identify concepts, or non-document resources. If a URI happens to express scheme that suggests that it can be dereferenced, it is not a requirement that a document resource is actually dereferenced by that URI.

Most people’s expectation of HTTP URIs is that they it can always be dereferenced. There is a common assumption that an HTTP URI must point to a document. If it document resources is not available at that URI, that is you get a 404 error, then the URI is somehow bad. Just because the server could not locate document or a representation for the URI, does not mean that the HTTP URI is an invalid identifier.

The finer bits of this issue are summed up in httpRange-14 as well as this article by Xiaoshu Wang. The concepts around httpRange-14 are deep , but I think it’s these types of ideas that trips people up a lot. IMHO, it’s one of those concepts that gets muddled in the great internet telephone game that causes more confusion. For example, it seems that people are under the impression that if a URL does not express a file extension, then it represents a concept and therefore is a URI, but it just doesn’t work that way.

A URL is a URI and a URI can be used to represent anything. Furthermore, each URI is unique. This is why you cannot assume that http://www.abc/home is the same as http://www.abc/home.html just by looking at the URI. These are both distinct URIs that may or may not represent the same resource. Because URIs are opaque, you as the client should not be attempting to make any decisions about the URI.

There’s been a lot of activity recently around highly optimized, binary serialization formats such as Google Protocol Buffers and Thrift. There have been some attempts to include formats such as Protocol Buffers into their “REST API” because of perceived performance benefits without consideration of the downside of an IDL format with respect to REST.

To illustrate why Protocol Buffers inherently adulterate REST architectural style, I’ve compiled the following points:

Imposes a Tight Coupling

This tight coupling is considered a REST anti-pattern and should be avoided. Protobuf over HTTP is probably a form of RPC-URI tunneling, it is not REST. In order to work with protobufs efficiently, both the client and server must have code generated by the .proto definition.

Strongly Typed Resources

A key point made my Roy T. Fielding in one of his more informative blog posts is that:

A REST API should never have “typed” resources that are significant to the client. Specification authors may use resource types for describing server implementation behind the interface, but those types must be irrelevant and invisible to the client. The only types that are significant to a client are the current representation’s media type and standardized relation names.

I’m not totally sure I’ve got this one 100% correct, but it would appear that the use of protobufs is now also exposing typed resources to the client. Additionally, there is no means to specify which type to ask for. Which leads me to my next point:

Ambiguous Media Type

Subbu Allamaraju has pointed out that the protobuf media type doesn’t doesn’t convey enough information as to indicate what message type is in the protobuf representation in a post about a Protobuf provider for JAX-RS. Protobuf doesn’t have an official media type, but folks generally use one of the following media types:

     application/x-protobuf
     application/vnd.google.protobuf

Protobufs are not generic and the representation contains data for a very specific message. Furthermore, the serialized form contains no information as to what type(s) it represents. So although you may have specified the media type in the request, there is no mechanism to specify which protobuf message we actually want. One suggestion as to how this might be resolved is to specify the .proto package and message name by using a parameter:

     application/vnd.google.protobuf;proto=mypkg.MyMessage

The approach seems reasonable enough. But as Subbu also points out, this solution also requires that the .proto be shared between the client and server in order to establish the binding. Clearly there’s a number of options that could be applied share the .proto definition, but all of them involve some type of external configuration in order to resolve the .proto since the protobuf wire format is not self-describing.

Self-Describing formats must be Self-Describing

Protocol Buffers are not self-describing by design. The Google documentation even states that:

Protocol Buffers do not contain descriptions of their own types. Thus, given only a raw message without the corresponding .proto file defining its type, it is difficult to extract any useful data.”

This isn’t necessary a bad thing in general, but it does violate a core tenet or RESTful architecture. Section 5.2.1.2 of the Roy T. Fielding’s dissertation states that a proper representation consists of the following:

  • The data
  • Metadata that describes the data
  • Optional metadata about the metadata, usually used to for integrity checking.

Protocol Buffers only handle the data. Google has presented an option for making protobuf messages self-describing. While this works, it still has three fundamental flaws:

  1. The SelfDescribingMessage itself is not self-describing ;)
  2. There’s still a tight coupling between client and server for the SelfDescribingMessage as generated code is still required on both client and server.
  3. It doesn’t address dependency resolution. That is, message you’re sending over might extend or depend on other .proto definitions. How you resolve those dependencies is a challenge.

The dependency resolution is no small challenge and becomes a major headache if you’re extending messages from other parties.

Application State is not Hypermedia driven

Protocol Buffers do not have a means to describe links to external messages. Most applications I’ve encountered that use protobufs either send the entire message tree in a single call or there is some type of ID value that the client will have to dereference somehow. The latter ultimately results  in either forcing the client to infer and generate URLs, which is yet another REST anti-pattern.

Wrapping Up

This isn’t to say that Protocol Buffers are inherently bad. Google has proven that protobufs have value when used as intended. Outside of an RPC system, protocol buffers are really don’t seem appropriate for web applications who claim to be RESTful. Of course, I could be complete wrong here and I’m sure the internets will be certain to let me know.

Without a doubt, the URL vs. URI post is by the most visited page on this blog. Even so, there’s still a lot of confusion on the topic and so I thought I’d break it down in less words. The original post was slightly misleading in that I attempted to compare URI to URL, when in fact it should have defined the relationship between URI, URL, and URN. In this post, I hope to clear that in more concise terms. But first, here’s a pretty picture:

uri_class_diagram

Both URLs and URNs are specializations, or subclasses of URI. You can refer to both URLs and URNs as a URI. In applictaion terms: if your application only calls for a URI, you should be free to use either or.
Now, here’s where the big difference between URN and URL: a URL is location bound and dereferencable over the web. A URN is just a name and isn’t bound to a network location. However, BOTH are still valid URIs. Now, if the application requires a URI that is bound to a network location, you must use the specialization of URI called URL.

Remember that URI stands for Uniform Resource Identifier, which is used to identify some “thing”, or resource, on the web. Both URLs and URNs are specialization’s (or subclasses if you will), of URI. You’d be correct by referring to both a URL or URN as a URI. In applictaion terms: if your application only calls for an identifier, you should be free to use either a URL or a URN. For brevity, you can state that the application simply requires a URI and the use of a URL or URN would statisfy that requirement.

Now if your application needs a URI that dereferencable over the web, you should be aware of the difference between URN and URL. A URL is location bound and defines the mechanism as to how to retrieve the resource over the web. A URN is just a name and isn’t bound to a network location. For example, you may have a URN for a books ISBN number in the form of urn:isbn:0451450523. The URN is still a valid URI, but you cannot dereference it, it’s just a name used to provide identity. So to put in simpler terms:

  • A URI is used to define the identity of some thing on the on the web
  • Both URL and URN are URIs
  • A URN only defines a name, it provides no details about how to get the resource over a network.
  • A URL defines how to retrieve the resource over the web.
  • You can get a “thing” via a URL, you can’t get anything with a URN
  • Both URL and URN are URIs as the both identify a resource

There some other items that need clarification based on some comments I’ve received from the original post:

  • Elements of a URI such as query string, file extension, etc. have no bearing on whether or not a URL is a URI. If the URI is defines how to get a resource over the web, it’s a URL.
  • A URL is not limited to HTTP. There are many other protocol schemes that can be plugged into a URL.
  • If a URL defines a scheme other than HTTP, it does not magically become a URI. The URI defines how to get the resource, whether it be HTTP, FTP, SMB, etc., it’s still a URL. But because the URL identifies a resource, it’s a URI as well.

Yeah, I’ve probably repeated myself a few times, but I wanted to stress a few points.

There’s also been some confusion about when to use the term URI. As I stated in the original post explained above, it depends on what you’re doing. If everything your application does involves accessing data over the web, you’re most likely using URL exclusively. In that case, it wouldn’t be a bad thing to use the term URL. Now, if the application can use either a network location, or a name, then URI is the proper term. For example, XML namespaces are usually declared using a URI. The namespace may just be a name, or a URL that references a DTD or XML Schema. So if you’re using a URL for identity and retrieval, it’s probably best to use URI.