<M <Y
Y> M>

Constellation Games Bonus Stories Now CC-Licensed: A few months ago when the Constellation Games serialization ended, some of the subscribers got four short stories along with their compiled ebooks; stories set before, during, and after the novel. The long-term fate of those stories was unclear. My publisher and I wanted to keep them scarce for a while to reward the loyalty of high-tier subscribers, but writing and editing these stories was a lot of work, so we wanted to make them available to the general CG-reading public. Possibly in exchange for money.

But it turns out there's not much money in nickel-and-diming you (specifically, there's about $0.15), so we've agreed to make all four stories available under the CC-BY-SA Creative Commons license. That's about seventeen thousand words of free fiction: the post-scarcity family drama of "The Time Somn Died", the foul-mouthed artistic angst of "Found Objects", the headshot violence of "Dana no Chousen", and the bubble-pipe erudition of "Pey Shkoy Benefits Humans".

The catch is that the stories contain spoilers for Constellation Games, and won't really make sense unless you read the novel first. And the novel still costs $5. At least, that's the pro forma warning I feel like I need to give you. But I remember when I was a kid and I discovered that the Arvin Public Library had the third book of the Hitchhiker's Guide trilogy but not the first two. I had no idea what was going on, who these characters were or why they were stranded in caveman times, but I devoured Life, the Universe, and Everything, reading it multiple times, and the lack of knowledge as to what was going on just made me determined to get a ride to the library in Bakersfield where I could check out the books that would explain it.

So... go ahead and read the stories first, if that's your thing. I think they might pique your curiosity. And remember that you can also read the first two chapters of Constellation Games online.

PS: if you order Constellation Games from the publisher you'll now get PDF copies of the bonus stories along with the ebook.

[Comments] (1) End-of-Year Film Roundup: I was gonna wait til the end of the month for this but I have seen so many great movies recently that I want to tell you about them now.

This is a combination of movies I watched at the Museum of the Moving Image, usually with Sumana, and Criterion Collection movies, hurriedly purchased during the recent half-price sale, which we watched at home. I've put them roughly in reverse chronological order of when we watched them. Sumana also put up some short reviews recently. Don't want to read this huge post? Read Sumana's entry instead!

Incidentally, I love the name "Criterion Collection." "We only select movies that meet... a criterion!" It's like the "Un Certain Regard" award they give out at Cannes. I imagine a French person shrugging and going "eeeeeeeh..."

Update: Gonna post the rest of the movies I see this year here, again in reverse chronological order.

Notes On (My) Fiction: Yesterday I finished a draft of a second story in the universe of "Let Us Now Praise Awesome Dinosaurs" (working title: "Grand Theft Carnosaur"). It needs some work, but that's what writing group is for. I'm cautiously optimistic. While working on the story I got a concept for a third story in that universe, so maybe I can make it a trilogy. No, a cycle! A motor-cycle.

My actual point here is that while working on "Carnosaur" I discovered a Tumblr full of fan art for "Let Us Now Praise Awesome Dinosaurs", done for a school project! Most of the story is illustrated: the gun store, the motocross race, the news interview, Cass's accident, the capture, talking with the lawyer and going back to Mars. A "cover" was promised but never posted.

"Dinosaurs" got a lot of links when it was published, but no actual reviews, so I was surprised to find two reviews of "Four Kinds of Cargo". First, from Locus: "A lot of silliness and absurdity that ends surprisingly on a heartwarming note." You could review almost any piece of my fiction as "A lot of silliness and absurdity that ends surprisingly on a ________ note."

Tangent's review is longer, more reserved but overall positive:

“Four Kinds of Cargo” is a science fiction story about science fiction characters basing their lives around a science fiction story and its characters. It’s metafiction in a neat, innocuous disguise... Its major drawback is an unavoidable one – the prose simply isn’t very good. But to succeed as the kind of multi-referential system it sets out to be, I don’t think this story could have been written in any other way. The cleverness of the premise and the recognition of what’s been pulled off both explain (if not demand) and make up for the lacklustre prose. This one made me want to grimace as I started reading it; by the end I wanted to applaud.

I'll take it.

"Let Us Now Praise Awesome Dinosaurs" - Illustrated!: It seems like only a week and a half ago, I told you about my discovery of "Awesome Dinosaurs" fan art. Well, now it turns out the artist, Lisa Imas, turned the story into a (one-off) printed book!

Lisa sent me some pictures once she was done, and I got permission to host a PDF of the book on the "Awesome Dinosaurs" story page, under the same BY-NC-SA license as the story itself. Check it out--the story is now fully illustrated.

Artist's commentary:

The cover displays the tragedy inherent in how any time we put someone or something on a pedestal we are only yadda yadda it’s dinosaurs on motorcycles, okay.

I especially like this understated piece:

More news of my writing coming soon!

[Comments] (3) Year's Best: "Four Kinds of Cargo" will be appearing in the 2013 edition of Prime Books's "The Year’s Best Science Fiction & Fantasy". That's me in the same book as Elizabeth Bear, Ursula K. LeGuin, Kelly Link, Robert Charles Wilson, and other luminaries.

Strange Horizons Reviews "Constellation Games": I've been nervous about this review all week, but it's very positive:

Constellation Games is a very funny book, with an effective sweep into pathos that delivers a powerful message... Like the Ignobel awards, Constellation Games makes you laugh, and then it makes you think.

Definitely the first review to call the naming of the Constellation species "an effective piece of othering".

[Comments] (6) RESTful Web APIs: I guess it's time to announce my next book project. Mike Amundsen and I are working on a book for O'Reilly called RESTful Web APIs, a follow-up to 2007's RESTful Web Services. Our deadline is the end of March 2013, and the book should come out a few months later. (Here's Mike's announcement of the project.)

Here's my announcement of RESTful Web Services from about six years ago. You can see how far we've come since then.

In 2008 I came up with the now-famous "maturity heuristic" (aka the "RMM") for quickly judging the quality of an API. If you go back and look at RWS through the lens of the maturity heuristic, you'll see that it spends a lot of time trying to get the reader to grasp the concepts behind Level 1 services: that URLs identify resources, and that resources are the proper targets of HTTP requests. That's because back then, Level 1 was about the best you could expect from a "REST" design.

RWS spends a whole chapter treating Amazon S3 as though it were a great example of RESTful design, because in RMM terms it made it all the way to... Level 2. RWS spends another chapter arguing for the legitimacy of REST against a thriving part of the industry that's content at Level 0.

We don't live in that world anymore. I'd say the modal RMM level of a new "REST" API today is 2. Most of the 2007-era arguments have been rendered irrelevant (SOAP vs. REST, the usefulness of PUT) or been given generally accepted best practices (URL formats). Restful Web Services was the first book-length treatment of REST; there are now over ten books on REST from O'Reilly alone. There are lots of development tools that make it really easy to crank out a Level 2 service.

In short, a lot of gravel- and rock-sized problems have been excavated, revealing two boulder-sized problems. I mentioned these two problems in my QCon talk "How to Follow Instructions" (available as video in hour-long version and in a half-hour condensed version presented at RESTFest; see also my QCon slide deck and speaker notes). Now I'll state them explicitly as the two major problems I want to address with RESTful Web APIs.

Duplication of effort

Here's an article from May on Programmable Web, a great site that tracks the world of public APIs: "53 Microblogging APIs: Twitter, TwitPic and What The Trend". Fifty-three was really the number of organizations publishing microblogging APIs, and some of them are utility APIs rather than "microblogging APIs" per se, but after doing some spot checks I do believe there were approximately fifty-three distinct APIs.

Should there really be fifty-three distinct APIs in this field? What if there were, like, five? We're not talking about something complicated, like insurance policies or regulatory compliance. We're talking about posting a little bit of text to a user account. Can we at least get down to ten?

No, apparently not. Like I said, that number was from May. There are now fifty-seven microblogging APIs. Well, damn. What if we got together and hammered out a standard, interoperable microblogging API? Sounds great, except nobody's interested. Evan Prodromou tried that with OStatus, and nothing came of it. You could use AtomPub as a microblogging API, pretty much unmodified, but nobody seems to want to.

The original RESTful Web Services sets out a design procedure for taking your problem domain and turning it into an API. But there's a big problem with this procedure: it doesn't consider the possibility that fifty-six other people may have already done the work for you.

Back in 2007, that possibility was remote. There was one microblogging API. I had to scrape the barrel pretty thin to find enough quasi-RESTful example APIs to fill Appendix A. Now the big problem is too many APIs. When you design the fifty-eighth microblogging API you're limiting your audience and wasting your users' time.

This is a really huge problem and we won't solve it with a book. But we can point out that it's a problem and take the first step towards mitigation. In RESTful Web APIs we present a new design procedure that focuses on reusing existing designs, coming up with new stuff to fill any gaps, and then publishing the new stuff for the benefit of a) your users and b) API developers who come after you.


Whatever influence RESTful Web Services has had, it stops dead at RMM level 3, the hypermedia level. In 2012, the modal new "REST" API is at level 2. It has been level 2 for a while, and will continue to be level 2 unless something changes. Most architectures don't support hypermedia very well (or at all), and a lot of developers still don't understand it.

That's understandable. To the programmer brain, hypermedia is weird. When you read RWS it's possible to just skip the parts about hypermedia, and I get the feeling a lot of people did. There's stuff in RWS that is now outdated, and stuff that was useful for dealing with 2007's problems but that I now consider just plain wrong. Most of that stuff has to do with hypermedia.

RESTful Web APIs is tightly focused on hypermedia--you will not be able to skip the "hypermedia parts"--and it deals with 2013's problems. Some specific shortcomings of RWS we'll address:

  1. We as developers have a strong desire to export our server-side object models as APIs. This is the idea behind JAX-RS. It's the idea behind lazr.restful, the framework I developed to make the Launchpad web service. But it's also the idea behind SOAP, and it's how we got fifty-seven microblogging APIs.

    This desire isn't technically at odds with the use of hypermedia, but it does tend to use hypermedia only to describe safe state transitions (i.e. to link resources together), and RWS didn't really go further than that.

  2. In 2007 there were no hypermedia formats based on JSON, but JSON-based representations were becoming overwhelmingly popular. RWS does not offer advice for this scenario. Developers either made up their own one-off hypermedia formats (as I did with the Launchpad web service), or, more commonly, ignored the hypermedia constraint. Today JSON has a number of general-purpose hypermedia formats (like Siren, Collection+JSON, and HAL), and we'll cover them in RWA.
  3. In RWS I was very dogmatic about avoiding overloaded POST. I felt strongly about this because I really needed to yank people out of the SOAP-RPC mindset. But I've come to accept that overloaded POST exists for a reason: to convey state transitions that don't map naturally onto one of the other HTTP methods.

    These state transitions are legitimate if they are described by hypermedia controls, as they are on the Web. They're not just hacks to get around the fact that HTML can't describe PUT and DELETE methods. Prohibiting overloaded POST in the name of the uniform interface forces designers into complicated workarounds to minimize the difference between their application semantics and the protocol semantics of GET/PUT/POST/DELETE. Those workarounds usually reflect the object model the designers already defined for their CRUD databases. Or, the designers give up, use overloaded POST without using hypermedia to describe the state transitions, and feel guilty about it.

    Besides which, forbidding overloaded POST means that you can't use HTML, the world's most popular hypermedia format. That's a big problem.

The title

As I said, this is a brand new book, not a second edition of RESTful Web Services. The only major things we're reusing are the appendices dealing with HTTP headers and response codes. To signify the handoff, we're changing the name.

RESTful Web Services was a great name in 2007, but it's not so good now. See, when SOAP went down, it took the term "Web Service" with it. "Web Service" is now an enterprise software term. Everywhere else it's all "API API API".

As I mentioned last year, this is backwards. The SOAP approach is to make a remote service look like a local library. (This idea is not limited to SOAP, of course.) Whereas the RESTful believe that a remote service should look like the Web. (Whatever that means.)

But I'm not gonna re-litigate that argument. "Web Service" is dead, we're stuck with "API", and the name of the book needs to change. "RESTful Web APIs" is a direct translation of "RESTful Web Services" into 2013-speak. It keeps continuity with the old book, but it's a new title for a new book.


If you want to be a beta reader, let me know (via comment or email to leonardr@segfault.org). I'll get in touch with you around the end of March, or possibly earlier. Update: We've got a lot of beta readers and we're no longer accepting applications.

Once in a while I add a section to a chapter called "The Hypermedia Zoo", which takes a not-too-detailed look at a lot of hypermedia-aware data formats to demonstrate their diversity. I'm always on a low-level search for more hypermedia formats, and if you name your favorites in the comments I'll take a look. Don't worry about duplicating my list; I also want to see what springs to mind when you think "hypermedia format".

There's also a shorter section called "The Semantic Zoo" which talks about interesting domain-specific data standards. I'm mostly interested in reusable profiles (the IANA registry of link relations, microformats, schema.org microdata, Dublin Core), but I'm also interested in pointers to standalone data formats like Activity Streams. There's a whole lot of stuff out there and I'm not confident that I've seen even half of it.

[Comments] (2) new robotfindskitten!: It's a big day for announcements. There's a new "Mayan Apocalypse" version of robotfindskitten, due largely to to the work of new dev team member Eric S. Raymond.

My major contribution to the release was editorial. I consolidated the list of NKIs with lists produced for other ports (notably Dave Griffith's Frotz port). I removed some stupid fifteen-year-old jokes, and added new stupid jokes. The end result is that this version of rfk ships with 701 high-quality NKIs, versus about 400 NKIs of wildly varying quality.


Unless otherwise noted, all content licensed by Leonard Richardson
under a Creative Commons License.