mark nottingham


Server-Sent Events, WebSockets, and HTTP

Sunday, 20 February 2022

The orange site is currently discussing an article about Server-Sent Events, especially as compared with WebSockets (and the emerging WebTransport). Both the article and discussion are well-informed, but I think they miss out on one aspect that has fairly deep implications.

Designing Headers for HTTP Compression

Tuesday, 27 November 2018

One of the concerns that often comes up when someone creates a new HTTP header is how much “bloat” it will add on the network. This is especially relevant in requests, when a little bit of extra data can introduce a lot of latency when repeated on every request.

How to Think About HTTP Status Codes

Thursday, 11 May 2017

There’s more than a little confusion and angst out there about HTTP status codes. I’ve received more than a few e-mails (and IMs, and DMs) over the years from stressed-out developers (once at 2am, their time!) asking something like this:

Five Reasons to Considering Linking in Your HTTP APIs

Sunday, 23 June 2013

There’s been a lot of interest in and effort expended upon “hypermedia APIs” recently. However, I see a fair amount of resistance to it from developers and ops folks, because the pragmatic benefits aren’t often clear. This is as it should be, IMO; if you’re not able to describe concrete benefits without hand-waving about the “massive scale of the Web.”

Indicating Problems in HTTP APIs

Wednesday, 15 May 2013

A common part of HTTP-based APIs is telling the client that something has gone wrong. Most APIs do this in some fashion, whether they call it a “Fault” (very SOAP-y), “Error” or whatever.

Evolving HTTP APIs

Tuesday, 4 December 2012

One of the most vexing problems that still seems to be facing people when I talk to them about HTTP APIs is how to handle versioning and extensibility – i.e., how they evolve.

OPTIONS is Not the Method You're Looking For

Monday, 29 October 2012

Once in a while, people ask me whether they should use the OPTIONS HTTP method, and whether we should try to define formats for discovering resource capabilities with it.

Why PATCH is Good for Your HTTP API

Wednesday, 5 September 2012

A common problem for APIs is partial update; when the client wants to change just one part of a resource’s state. For example, imagine that you’ve got a JSON representation of your widget resource that looks like:

Bad HTTP API Smells: Version Headers

Wednesday, 11 July 2012

One thing I didn’t cover in my previous rant on HTTP API versioning is an anti-pattern that I’m seeing a disturbing number of APIs adopt; using a HTTP header to indicate the overall version of the API in use. Examples include CIMI, CDMI, GData and I’m sure many more.

HTTP API Complexity

Monday, 25 June 2012

@dret: if your scenario is homogeneous and models are harmonized across participants, #REST is of limited utility for you.


Tuesday, 17 April 2012

Erik Wilde - otherwise known as dret - has published an Internet-Draft for a “profile” link relation type:

User Personas for HTTP APIs

Saturday, 14 April 2012

When you’re designing HTTP APIs, you need to keep a lot of concerns in mind. Stealing a page from XP, let’s look at some possible personas and their user stories for HTTP-based APIs:

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.

Web API Versioning Smackdown

Tuesday, 25 October 2011

A lot of bits have been used over on the OpenStack list recently about versioning the HTTP APIs they provide.

Thinking about Namespaces in JSON

Wednesday, 12 October 2011

Since joining Rackspace to help out with OpenStack, one of the hot topics of conversation I’ve been involved in has been extensibility and versioning.

Your REST worries have ended.

Tuesday, 22 March 2011

Now, you can test any URL to instantly determine if it’s RESTful.

RFC 5785 - Well-Known URIs

Wednesday, 7 April 2010

One of the nagging theoretical problems in the Web architecture has been finding so-called “site-wide metadata”; i.e., finding something out about a Web site before you access it. We wrestled with this in P3P way back when, and the TAG took it up after that.

WS-REST (heh, heh)

Friday, 15 January 2010

If you haven’t seen it already, check out the Call for Papers for the First International Workshop on RESTful Design (WS-REST 2010), where I’m on the program committee, along with many of the usual suspects.

Stop it with the X- Already!

Wednesday, 18 February 2009

UPDATE: RFC6648 is now the official word on this topic.


Thursday, 16 October 2008

Metadata discovery is a nagging problem that’s been hanging around the Web for a while. There have been a few stabs at this problem (including at least one by yours truly), but no real progress.

Moving Beyond Methods in REST

Thursday, 20 March 2008

Having complained before about the sad state of HTTP APIs, I’m somewhat happy to say that people seem to be getting it, producing more capable server-side and client-side tools for exposing the full range of the protocol; some frameworks are even starting to align object models with resource models, where HTTP methods map to method calls on things with identity. Good stuff.

Watching WADL (and other rambling thoughts)

Monday, 21 January 2008

I’m following the discussion of RESTful Web description in general, and WADL in particular, with both difficulty and interest (see Patrick and Joe’s thoughts for a nice contrast).

WADL Documentation XSLT Updated

Friday, 2 November 2007

I’ve updated the WADL documentation stylesheet, primarily to:

ETags, ETags, ETags

Tuesday, 7 August 2007

I’ve been hoping to avoid this, but ETags seem to be popping up more and more often recently. For whatever reason, people latch onto them as a litmus test for RESTfulness, as the defining factor of HTTP’s caching model, and much more.

URI Templates Redux

Saturday, 28 July 2007

URI Templates -01 is now an Internet-Draft.

Squid is My Service Bus

Sunday, 29 April 2007

The QCon presentation ( slides) was ostensibly about how we use HTTP for services within Yahoo’s Media Group. When I started thinking about the talk, however, I quickly concluded that everyone’s heard enough about the high-level benefits of HTTP and not nearly enough details of what it does on the ground. So, I decided to concentrate on one aspect of the value that we get from using HTTP for services; intermediation, as an example.

REST Issues, Real and Imagined

Tuesday, 27 February 2007

I think that most of the debate about REST focuses on the wrong things, leading developers down the garden path at the expense of their productivity and the success of their projects. Time and time again, I’ve seen folks who are new to REST get caught up on small stuff like this;


Wednesday, 7 February 2007

Yahoo! (finally!) released Pipes as a beta today; congrats to the very talented team that put this together.

Schema for JSON

Thursday, 30 November 2006

One of the perceived deficiencies of JSON is that it doesn’t have a schema language. I say “perceived” because the problems that a schema language brings often outweigh the benefits; after all, look at the mess that XML Schema is in.

Wanted: HTTP Yahoo!s

Tuesday, 17 October 2006

My team at Yahoo! is looking for a mid-level developer (5-10 years experience) to help build our HTTP/REST toolkit, among other things.

Bringing Back the Link - With a Twist

Thursday, 22 June 2006

Recently, there’s been a resurgence for the Link element in HTML; everything from Microformats to Atom autodiscovery is using it. This isn’t surprising; as machines start processing Web documents more, it’s necessary to use hyperlinks — the foundation of the Web — to tie resources together, without getting in users’ faces.

Microsoft's RESTful Robots

Tuesday, 20 June 2006

A friend (who shall remain anonymous) pointed me to Microsoft’s announcement today regarding their foray into robotics, of all things. My eyes glazed over until they rested upon the Microsoft Robotics Application Model;

Are Namespaces (and mU) Necessary?

Friday, 7 April 2006

It’s become axiomatic in some circles — especially in WS-* land, as well as in many other uses of XML — that the preferred (or only) means of offering extensibility is through URI-based namespaces, along with a flag to tell consumers when an extension needs to be understood (a.k.a. mustUnderstand).

WS-Transfer, WAKA and the Web

Wednesday, 15 March 2006

Microsoft and friends (of the keep your enemy closer variety, I suspect) have submitted WS-Transfer to the W3C. I found the Team comment interesting; e.g.,

REST vs..?

Monday, 7 November 2005

More and more people are getting turned on to the advantages of using REST as a higher-level abstraction for networked applications, often comparing it favourably to SOAP and Web services.

Why Just GET and POST?

Saturday, 22 October 2005

Why is it that Web browsers — Amaya excluded — don’t support PUT and DELETE? After all, if there are enough VCs foolish enough to part with their money for something like Flock, surely we could at least support all of HTTP’s methods.

One Description to Bind them All? Nah.

Friday, 8 July 2005

You can describe just about anything with sufficient precision in plain English, given enough words. In practice, this doesn’t happen; specialised fields — whether science, finance or art — develop specialised jargon as a shorthand for concepts that are well-understood in that field. It gives greater precision, easier flow of ideas, and yes, it raises the bar to entry for newcomers.

Web Description at the W3C

Tuesday, 24 May 2005

The W3C has just started a mailing list for discussion of Web description formats;

WADLing towards Web Description

Wednesday, 18 May 2005

Marc Hadley has released WADL in the wild, and I’m intrigued; based on a first look, I’d say it’s the most promising Web (as opposed to Web Services) description language yet.

Questions Leading to a Web Description Format

Friday, 29 April 2005

A while back, I published a series of entries ( 1, 2, 3, 4) about would-be Web Description Formats, with the intent of figuring out which (if any) is suitable, or whether a new one is required.


Monday, 21 March 2005

A while back, I wrote up a description of a pattern for avoiding messages like “ click submit only once.” I didn’t do much after that, because I’ve been a bit busy, and because I wanted to do some implementation of a more general HTTP framework before I wrote a more formal document.

The Map is Not the Territory

Monday, 7 February 2005

Werner makes an excellent point;

Why POST is Special

Sunday, 10 October 2004

In a recent post, Don gave his take on the enlightening nature of WS-Transfer:

The Whole Web in a Python Dictionary

Saturday, 31 July 2004

A few days ago I blogged a straw-man API for client-side HTTP based on dictionaries. This turns out to be well-aligned with a project I’ve had on the back burner for a while; coming up with some Python APIs for HTTP that are usable, encourage good practice, and well-aligned with the specifications.

Dictionary as API?

Monday, 26 July 2004

From the Daily Python URL comes another noteworthy API for XML; XMLFragment. I haven’t tried it yet (it doesn’t appear to be separately available, hint, hint), but I like the look of it.

Use Cases for Web Description Formats

Monday, 14 June 2004

One thing about Web description formats that hasn’t seen much discussion yet is how people intend to use them.

Using WebDAV as a Description Format for REST

Tuesday, 27 April 2004

In the past, I’ve talked about reusing WSDL as a format for describing Web resources, as well as coming up with a bespoke format.

Sean’s Words of Wisdom

Tuesday, 20 April 2004

Sean McGrath always has carefully considered positions, and he hits it out of the ballpark with this one. A few thoughts;

Asynchrony: There Is No Spoon

Monday, 19 April 2004

One of the things that people find compelling about Web services is its promise of asynchrony. “HTTP is only request/response, and therefore synchronous; it’s terrible for long-lived business processes, where the server needs to contact the client at some arbitrary time in the future” they say.

Behind the Scenes at Your (very) Local Music Store

Monday, 29 March 2004

Aaron Swartz has started to document the iTunes Music Store; this is a good example of a non-browser, cross-platform application reusing HTTP. It would be interesting to see the interface documented on a per-URI basis.

Messages vs. Files

Saturday, 7 February 2004

Jon Udell is thinking about the benefits of data being globally available, rather than localised to a machine. I’m in complete agreement; in the last two years, I’ve used Linux, Windows and Mac OSX on the desktop, leading me to be ruthless about data portability.

What is NetKernel?

Tuesday, 3 February 2004

Just got some mail regarding the Cacheability Engine which led me to NetKernel;

Decentralised Registration

Monday, 12 January 2004

Wouldn’t it be great if, whenever a business, government organization or just the guy down the block came up with a new format for their documents, they could easily get a media type, so that the format would be a first-class citizen on the Web?

Why Do Web Server APIs Suck So Much?

Monday, 8 December 2003

HTTP provides considerable benefits to Web applications that take advantage of it; everything from scalability (through caching), client-integrated authentication, automated redirection, multiple format support and lots more.

A Description Format for REST

Sunday, 7 December 2003

Adam asks if there’s a description format for REST. I don’t know of any that have wide acceptance (and I think the hard-core RESTafarians will answer “REST is self-describing, that’s the point” ;) but I have been noodling on something for my own purposes.

Loose Coupling, Late Binding and REST

Friday, 3 October 2003

Mark Baker says that REST is SOA + late binding. While I see the truth in this, I think it’s pretty orthogonal, and it’s not that compelling for most SOAish folks.

Click Submit Only Once

Saturday, 13 September 2003

I shudder when I see these words. Everyone I’ve asked has, at least once, gotten two orders of something online (personally, I’ve had the SonyEricsson store ship three duplicate orders); “Click Submit Only Once” is intended to stop that. The problem is, it puts me and every other shopper between a rock and a hard place.

Structured URIs

Monday, 11 August 2003

I just found a draft finding that the W3C TAG published about a month ago, regarding the use of metadata in URIs. This is very cool, and I especially like the emphasis on authorities’ ability to embed metadata in URIs.

Bees and Ants

Tuesday, 24 June 2003

The W3C Semantic Web wiki has an entry called ‘BeesAndAnts’ that very effectively conveys something that I’ve been trying to articulate for a while (and, as usual, failing). It’s not about the Semantic Web in my mind, so much as it’s about REST and Web Services (which means that there’s something to this Web architecture stuff yet, I think).


Thursday, 29 May 2003

Jonathan Rosenberg published a new Internet-Draft, XCAP, to the SIMPLE Working Group in the IETF. Here’s the skinny: