Skip to content

How to learn REST: A resource guide

I have a new software project in mind. I want to do it right. So I’ll use a RESTful web API. Which, of course, like any good software developer, I already understood pretty well, but I wanted to just brush up on my REST game, and make sure I got all the best practices down. Thus began my search on Amazon for a good book about REST. I found one. I read it. And I realized then that my previous “pretty good understanding of REST” was almost completely incorrect. And yours probably is, too.

Outlined here is my suggested reading list to familiarize yourself with REST (jump straight to the reading guide). So far, I have two books I recommend–the two I’ve read. I think I got lucky and read two good books, and I happened to read them in approximately the right order.

My primary goal is to help you, as someone who has a “pretty good concept of REST” which turns out to be mostly wrong, get to the right answer, with the least amount of effort and confusion.

First, a quick test to see if you have a “pretty good concept of REST which is mostly wrong”, or if you really understand it.

1. Do you know when to use the HTTP DELETE verb?
2. Do you know what an Accepts: header does?
3. Is it RESTful to send an HTTP GET request to http://example.com/?item=123&action=delete to delete an item?
4. Do you know which link types are acceptable within a REST API?

The answers are:

1. When you want to delete a resource. If you’ve never used or heard of the HTTP DELETE verb, you should read the rest of this document.
2. It tells the server which content type(s) the client is prepared to accept. If you didn’t realize the client could specify this, or when they might want to, you should read the rest of this document
3. No. In a proper REST API, an item deletion should always use a DELETE verb (not GET), or occasionally, a POST. GETs must always be *safe*–that is, they should never modify server data. If this is new to you, you should read the rest of this document
4. The answer is, it depends. But you should have a good idea of how to determine the proper link types *without reading human documentation* for a given REST API. If this is new to you, read on.

If you have a solid understanding of these four questions and answers, then you probably are in the minority who have a good, proper understanding of REST, and following this reading guide probably won’t teach you much.

Now for the list of books:

  1. REST in Practice: Hypermedia and Systems Architecture (or for Kindle)
  2. RESTful WebAPIs (or for Kindle)

But not so fast! These books overlap a bit, and they have different strengths and weaknesses. So let me offer my advice on the order in which to read these books.

REST in Practice is an excellent primer to REST. It does an excellent job of explaining the four levels of a REST service (Levels 0 through 3). Quoting from the preface of the book itself:

Like most of us, you’re probably already building something that feeds into the Web, and you’ve probably used tools and patterns for the Web that seem pretty useful. Then you’ve tackled typical enterprise problems and wondered why it can’t be as nice as the web stuff.

You may even be an enthusiast who has heard about REST and wants to know what it is all about. You want to learn about “hypermedia” and the REST architectural style so that you can build resource-oriented systems and implement sophisticated business protocols atop the Web.

This book will help.

And I agree completely. This book will help, by laying the conceptual foundations upon which REST rests. Where this book lacks is in the final chapters, in the discussion of hypermedia. I believe there are two primary reasons for this shortcoming. First, it’s just a plain confusing domain of information. And second, the book is nearly a century old (in Internet years– it was published in 2010), and the world of hypermedia has made many important advancements since then.

The book is fun to read. It follows the whimsical, but applicable, development of a coffee-ordering REST API for the fictional “Restbucks” Coffee chain, as it grows from employing a single barista, to becoming a chain with multiple locations and nation-wide loyalty programs and specials. This back story provides the necessary context for the REST concepts to fall neatly into place.

Aside from being dated, the book’s other weakness, in my opinion, is spending too much time on the specifics of client and server implementations details in Java and .NET. Don’t feel guilty for skipping these sections. Unless you’ve never written client or server code before, you probably won’t glean much of value from these sections. Skip them with impunity, if you wish.

I suggest you begin your reading with REST in Practice, and read chapters 1 through 4, and chapter 6 thoroughly. Chapter 5 ought to be at least skimmed. Beyond chapter 6, some good concepts are introduced, but they get muddled, and largely buried beneath the details of XML-rich document formats. At this point, it would be good to familiarize yourself with some of the concepts, by skimming chapters 9, and 10. Chapters 7, 8, and 11 cover mostly obsolete concepts. You should only need to read them if you’ll be using these specific formats. Read or skim chapter 12.

At this point, you should have a pretty good understanding of what a REST API is, and how to write one, except for one missing, and very vital piece. You’ll understand conceptually what Hypermedia is, and where it fits into the REST puzzle, but you won’t know how to use it. This is where my second reading recommendation comes in.

RESTful Web APIs is the new edition of the popular, but now out-of-print RESTful Web Services by the same author. The new edition focuses heavily on Hypermedia in the context of REST, and really picks up where you left off if you followed my advice above. It’s also 3 years newer than REST in Practice, which is a long time in an area of new technology, such as REST and Hypermedia. The 3 years make a huge difference! Where REST in Practice, for instance, recommended Atom, RESTful Web APIs points out that by the time of its publishing, Atom was all but obsolete, and provides several alternatives which will likely serve you better.

Chapters 1-2 will be review for you, if you’ve read REST in Practice. I suggest skimming them, though, just to give you some context, as the rest of the book refers back frequently to examples presented in these initial chapters. Chapter 3, while technically, also offers a fresh perspective on resources and representations, upon which the rest of the book builds. So I suggest reading it thoroughly.

Chapters 4-9 are the meat of the book, with the culmination in chapter 9, with a specific 7-step suggestion for designing your own API from the ground up. Those 7 steps, if not all of chapter 9, probably belong on a poster on your office wall, if you’ll be writing more than one API in your career.

Chapter 10 is more for reference, and provides a summary of readily-available Hypermedia formats for your perusal so you can pick-and-choose the bits to plug into your new API. You will probably want to just skim it, and read the sections that apply specifically to your problem domain.

Chapter 11 is essentially a whirl-wind repetition of REST in Practice‘s chapters 3 and 6. Skim it if you wish.

Chapter 12 covers RDF, and should be read thoroughly, if only to understand how RDF fits (and doesn’t) fit into REST.

Here’s my reading guide:

  • Read REST in Practice, Chapter 1: The Web as a Platform for Building Distributed Systems
  • Read RESTful Web APIs, Chapter 3: Resources and Representations

    RESTful Web APIs offers a newer, arguably healthier view of resources and representations. If you have both books at hand, I suggest reading this chapter immediately after chapter 1 of REST in Practice, just so you have both paradigms in mind. It will help you to be mindful of the differences as you read the rest of the material.

  • Read REST in Practice, Chapter 2: Introduction to Restbucks: How to GET a Coffee, Web Style
  • Read REST in Practice, Chapter 3: Basic Web Integration
  • Read REST in Practice, Chapter 4: CRUD Web Services
  • Read or skim REST in Practice, Chapter 5: Hypermedia Services

    I suggest reading this, for continuity, although it will be largely redundant with much of RESTful Web APIs, starting with chapter 4. If you’re in a hurry, you can skip this, though.

  • Read REST in Practice, Chapter 6: Scaling Out
  • Skim REST in Practice, Chapter 9: Web Security
  • Skim REST in Practice, Chapter 10: Semantics
  • Read or skim REST in Practice, Chapter 12: Building the Case for the Web
  • Skim RESTful Web APIs, Chapter 1: Surfing the Web
  • Skim RESTful Web APIs, Chapter 2: A Simple API
  • Read RESTful Web APIs, Chapter 3: Resources and Representations

    Only if you didn’t read this earlier. Or you may wish to re-read or skim through it to refresh yourself on the material.

  • Read RESTful Web APIs, Chapter 4: Hypermedia

    Much of the material in this and the following chapter was already touched upon in chapter 5 of REST in Practice, but it is given more attention here.

  • Read RESTful Web APIs, Chapter 5: Domain-Specific Designs
  • Read RESTful Web APIs, Chapter 6: The Collection Pattern
  • Read RESTful Web APIs, Chapter 7: Pure-Hypermedia Design
  • Read RESTful Web APIs, Chapter 8: Profiles
  • Read RESTful Web APIs, Chapter 9: The Design Procedure

    This chapter is the gold mine. This is where all the pieces you’ve been learning finally fall into place in a REST API of your own design!

  • Skim RESTful Web APIs, Chapter 10: The Hypermedia Zoo

    This is a summary of numerous existing Hypermedia formats (including Atom and AtomPub, covered in chapters 7 & 8 of REST in Practice). You’ll want to skim this, for an overview of available formats. But be aware that this book is already 2 years old, and there are new formats all the time. This won’t be the end of your search for existing formats!

  • Skim RESTful Web APIs, Chapter 11: HTTP for APIs

    REST in Practice covers these topics in greater detail in chapters 4 and 6.

  • Read RESTful Web APIs, Chapter 12: Resource Description and Linked Data

    Any forum post on REST these days talks about RDF, linked data, and a dozen other related buzzwords. This chapter helps explain what those are, and how they do (and don’t!) relate to REST.

That’s my suggested reading.

Please offer your feedback and questions below in comments. If you have any additional resources I should add to the list, please let me know!

List of French Minimal Pairs

I’m in the early stages of learning French. I recently read Fluent Forever: How to Learn Any Language Fast and Never Forget It by Gabriel Wyner, which I highly recommend to anyone trying to learn a language. One of the suggestions it makes is to spend some of your early time, before diving into vocabulary, on some ear training, to learn to distinguish between the new sounds in your target language. One way to do this is by studying “minimal pairs”–that is, words which sound the same, except for one, or sometimes two subtle sounds. Some common examples in English, which are usually difficult for English learners to master, are:

* Sheep and Ship
* Kiss and Keys
* Beach and Bitch
* Hungry and Angry

So in my quest to find French Minimal pairs, I decided to throw some computer programming skills at the problem. The result is a list of 2921 minimal pairs in the French language.

I took the top 10,000 words in the French language from Wikipedia, transcribed the words to the International Phonetic Alphabet with the help of the eSpeak software, then used my script to compare each pronunciation in the list with every other pronunciation in the list, and generate a list of words which match, except for one sound.

There is no doubt a lot of room for improvement. If you are the hacking type, please feel free to use and tweak my scripts (they aren’t pretty!) to accomplish your own tricks. The scripts are available on GitHub.

Creating a Debian package of a Go project

Go is all the rage these days, and I decided to give it a try. And as my company uses Debian packages to distribute our software, I need to package my new Go-written project for Debian. Mark Stapelberg has done a lot of leg work to find the best (and official!) ways of packaging Go projects for Debian. His Go Packaging page on the Debian wiki explains the “official” Debian way to build such a package, but it is painfully sparse when it comes to the technical details of how to build a Debian package of a Go project. So this is my ils of how to build a Debian package of a Go project. So this is my attempt to clarify some of the technical questions and their answers as I have them while building my first Debian/Go package.

This document is a work-in-progress, and I will be updating it as I progress with my Go/Debian project.

If you find any inaccuracies or outdated info on this page, please contact me, so that I can update it!

First, some background on Go development. This ought to be familiar to any Go developer, but some details are Debian-specific. From How to Write Go Code, we learn that all of our Go projects ought to live in a single, specific, directory structure, as such:

bin/
    hello                          # command executable
    outyet                         # command executable
pkg/
    linux_amd64/
        github.com/golang/example/
            stringutil.a           # package object
src/
    github.com/golang/example/
        .git/                      # Git repository metadata
	hello/
	    hello.go               # command source
	outyet/
	    main.go                # command source
	    main_test.go           # test source
	stringutil/
	    reverse.go             # package source
	    reverse_test.go        # test source

The important thing for us is to know which part of this tree comprises our Debian package. In the above directory tree, each of hello/, outyet/, and stringutil/ has the potential to be a Debian package. If we were to add debian/ directories to each of these, we would end up with the following structure for src/:

src/
    github.com/golang/example/
        .git/                      # Git repository metadata
	hello/
            debian/
	    hello.go               # command source
	outyet/
            debian/
	    main.go                # command source
	    main_test.go           # test source
	stringutil/
            debian/
	    reverse.go             # package source
	    reverse_test.go        # test source

Within the debian/ directory, you can create a standard Debian package using whatever means you prefer. I will only discuss the changes that are necessary for a Go project.

If your package will be used by others, you’ll want to follow the official Debian Go packaging guidelines, and use dh-golang which require you to Build-Dep on all of your dependencies (as normal!), and you should use the default debian/rules file. This will set your $GOPATH to /usr/share/gocode during the build process.

If, however, you are building a Go package just for your personal, internal use, or for testing purposes, you may wish to build a Debian package which has dependencies which are not packaged for Debian. This is a bit trickier (since it’s not supported by the official tools), and will result in a package that is unacceptable for the Debian (or Ubuntu) mirrors. But it can be quite useful, and this is precisely what I wanted to do. To do this, I started with the default debian/rules file linked above, then added a few changes. This is what I came up with:

#!/usr/bin/make -f
# -*- makefile -*-
# Sample debian/rules that uses debhelper.
# This file was originally written by Joey Hess and Craig Small.
# As a special exception, when this file is copied by dh-make into a
# dh-make output file, you may use that output file without restriction.
# This special exception was added by Craig Small in version 0.37 of dh-make.
GOPATH := $(shell cat ~/.gorc /etc/gorc 2> /dev/null | grep ^GOPATH= | head -n1 | cut -d'=' -f2)

GO := GOPATH=$(GOPATH) go
# Uncomment this to turn on verbose mode.
#export DH_VERBOSE=1

export DH_GOPKG := efsgithub.securewebportal.net/dc/golang-dc/dc-ldap

%:
	dh $@ --buildsystem=golang --with=golang

override_dh_auto_build:
	echo start
	$(GO) get
	$(GO) build
	echo end

override_dh_auto_test:
	$(GO) test

override_dh_auto_clean:
#       List any files built by your project here, to be removed by the 'clean' process
#	rm ...
	dh_auto_clean

With this debian/rules file, it is necessary to create a file, either ~/.gorc or /etc/gorc which contains, at least, a single line specifying your $GOPATH (in Bash syntax). Mine looks like this:

GOPATH=/home/jonhall/go

For additional reading:

No Brasil

That’s not a dis on Brazil, for those of you who don’t speak Portugues… that’s “In Brazil”…

Which is where I am, as of a week ago. I arrived last Saturday morning, and my friend Mariah met me at the airport with her two daughters, Isabel (10) and Stephany (15). Sunday we went to her church, which is quite small, and full of very friendly people. Mariah tells me I’m the “Pop Star” in the church Whatsapp group.. “O americano, o americano!” is apparently all they talked about for the first few days after my arrival.

My new bicycleSo far I’ve mostly been acclimating to the climate and the culture. I bought a bicycle a couple of days ago, for R$160 (aprox US$72). It’ll get me around for a month while I’m here, and the savings in bus fare will just about cover the cost of the bike in that time–not to mention it’s a lot more fun to ride a bicycle along the beach than to cram into a crowded bus with no ventilation.

I’m getting a tan.

My Portuguese is improving at an impressive rate. But it’s still pretty bad. I haven’t passed the Barry Farber fluency test yet–which is to have a conversation with a beautiful woman in the new language, and not remember which language you spoke the following day. Maybe I’ll achieve that before my stay is up–there is no shortage of beautiful women here to try with!

tacoBrazilian Barbecue is pretty amazing. The thing that surprises me the most is how similar it is to the Brazilian barbecue I’ve had in the U.S. and in Mexico. It comes out on a sword-like spit, it’s cut at your table to order. My experience with ethnic cuisine has usually been drastically different from the true, authentic version. Think Taco Bell versus real tacos.

Early in the week, I went to the local shopping mall, which is called “Shopping Vitória.” “Shopping” is an interesting word–an Anglicanism for “shopping mall.” But my favorite local Anglicanism is for a restaurant we all know and love… “Ouch Back!” You know… the Australian steak house. I hope they have a good referral program with the local chiropractor!

Friday, Sept 13, 2013 — Leaving the Americas

It’s a good thing my flight doesn’t leave until tomorrow. I’m sure flying on Friday the 13th would be a bad idea.

Approximately 1 am, I’ll be boarding a flight here in Mexico City, bound for Montreal. I’ll spend roughly 12 hours on the ground there, then fly to Paris, where I’ll be meeting up with a friend of mine for a 3-week whirlwind tour of France, Germany, Belgium, and England. October 4, my friend will return to Kansas, and I will stay in Europe a while longer, and hopefully take some French and/or Portuguese classes.

I’m both excited and nervous about this. It feels like the first time I’ll be venturing into a country where I don’t speak the language. But really, I did the same thing–and in a much scarier way–about 3 years ago, when I moved to Mexico. At the time, I spoke a token amount of Spanish. But the main thing is that now I speak (more or less) fluent Spanish, which paints my memory of early Mexican travel with a rose-colored light.

This last week I have really been enjoying Mexico City. I have a friend here with a nearly-complete apartment she’s not yet using, so I’ve been staying there, and riding my bicycle to area cafes to work. Then every night, around 9-10pm, when she gets off work, we’ve been going to dinner at other various local restaurants.

A favorite was the 50′s themed diner, which served baked potatoes named after Hollywood stars, alcoholic cocktails, the likes of which I had never seen before (I drank one with cucumber, cai seeds and, I think, vodka), and milk shakes.

I also enjoyed a Cuban restaurant, where I got to drink a Cuban beer for the first time (since Cuban-imported products are illegal in the U.S.).

And it probably goes without saying, the food is one thing I’m very eager to experience in Europe, too. I’ve been promised some home-cooked Belgian food by a coworker who lives there. And a good friend from high school will be introducing us to some German places and food. And of course, the cheese and wine in France are high on my list of things to try–if only I can figure out how to pronounce their names!

Day 31 – August 12, 2013: How many Mexican highway workers does it take to change a light bulb?

About a week and a half ago, I was driving near Querétaro, when the answer to this riddle became quite apparent:

Q: How many Mexican highway workers does it take to change a light bulb?

A: 50. One to change the light bulb, and 49 to redirect traffic.

Driving along the highway, I saw some orange cones, and a lone man in an orange vest, directing traffic to merge from the left lane into the right. This was followed by hundreds of traffic cones, but no sign of work whatsoever. After a mile or so, I saw another worker, waving traffic away from the left lane (never mind that nobody was in the left lane, thanks to the cones, and the previous redirection a mile earlier).

From this point, every hundred feet or so, I saw another man in an orange vest waving a flag, instructing me to continue not to merge back into the quarantined left lane. This went on for another mile or two.

Eventually, after about 3-4 miles of these cones and people waving at me, I saw, on the shoulder, a cherry-picker, holding a man high into the air, to change the light bulb on a street light.

Cute.

Mexican traffic often makes me chuckle. Which brings me to another encounter I had this morning.

Over the weekend in Guadalajara, we had a very severe thunder storm, complete with flooding (photos later), power outages, and many downed trees. This morning as I was driving to an appointment to replace my brake pads along Mariano Otero, one of the major roads through Guadalajara, the traffic lights were out, and there was a tree blocking a major portion of the road. So a traffic cop was at the intersection, directing traffic.

Until he saw me.

Or more precisely, until he saw my car.

He had me stop in the middle of the hectic intersection, to ask me about my car, and how much I would sell it for!!

I do get offers for my car all the time, as diesel Jettas are rare here… (this was at least my second one this week), but I’ve never had a traffic-directing police man hold up 6 lanes of traffic to ask me if I would sell it!

Day 26 – August 7, 2013

I don’t have much to write today. But I have a free moment, so I’ll write something.

I just walked back from the market, where I bought a liter of fresh carrot and orange juice for MXN$25 (US$1.97), and a mango to put on my steel-cut oats.

I’m in Guadalajara this week, staying with some friends, and venturing into the city to visit friends in the evenings after work. Last night I went to the home of the pastor of English Fellowship–the church I attended when I lived here. Tonight I’ll go salsa dancing.

My life as of late consists of working, and visiting friends. Much like when I was in Wichita, only these friends I haven’t seen for a while.

Next weekend I intend to go to Puerto Vallarta for a couple days.

Day 14 – July 26, 2013: Immigration office

Today I took my second trip to the Mexican Immigration office in San Miguel de Allende, Guanajuato. Also my third, fourth, and fifth.

In stark contrast to the good experience I had with the Mexican bureaucracy on Day 3, this experience left much to be desired.

I showed up about 9:30am yesterday, and was told of the requirements to finish my visa application:

  • 3 passport-sized photos
  • Wire a payment of $3,130 pesos at the bank
  • Photo copies of my passport
  • Fill out a simple paper form
  • Fill out an online form

Seems simple enough. It took a while to complete all these tasks, eat lunch, and return to the office. I returned at 12:55pm; five minutes before closing time (yes, they close at 1:00pm… huh?)

I had everything in order, except that I had filled out the online form incorrectly (with the wrong “reason”).

I was told to do it again, and return the next day. *sigh* Oh well.

9:15am I arrived with the new form today. I was told I had made an error. I failed to include my middle name this time, so the form did not match my passport exactly.

I walked across the street to a cyber cafe. For 3 pesos, I was able to fill out and print the form.

10:00am The new form had another error. I had entered the incorrect expiration date for my passport.

Back across the street. Fill out the form again.

10:30am Double-checking my form this time, I notice I had typoed my own middle name.

Back across the street. Fill out the form again.

11:00am Finally. Everything in order. My forms are accepted. I sign a few places.

Now I have an appointment for next Friday to return, when I believe I will be given my final Visa card, which allows me access into and out of Mexico as a temporary resident. Woot!

I am at a loss as to why they don’t just fill out the electronic form for you there at the office. It’s a half-page at best. Name, place of birth, nationality, passport number, and current (Mexican) address. It seems it would save everyone, including the staff at the immigration office, time to do it this way.

Day 6 – July 18, 2013: If you’re holding a beer, it doesn’t count as dancing

Last night I was invited to the Far West Rodeo club in Monterrey, Mexico for some live music. The MXN$150 (~US$12) cover included free drinks, so I had some cheap beer and come cheap pineapple juice with rum.

The music varied a little, including some Salsa and Cumbia, but mostly Tejano. As wikipedia points out, Tejano music is kind of a broad term for music which formed out of the combination of northern Mexican and southern U.S. influences. This was especially clear to me while listening to the band play a partly-Spanish, partly-English rendition of the Johnny Cash song Ring of Fire.

This was my first attempt to dance to the Tejano rythm, but I guess I did alright. It’s pretty simple. Too simple, really, for my taste. But I enjoyed watching others dance to the Tejano music, and to the Tejano-Cumbia rythms. I know a little Cumbia, but not enough to really hold my own yet. And watching the other couples dance last night, while entertaining, wasn’t especially educationally, as the vast majority were dancing holding beers or cigarettes. And in my opinion, you can’t really dance without both hands free.

I think we’ll hit up a salsa club here in Monterrey later this week. I’m hoping!

Day 5 – July 17, 2013: Train-dodging in Monterrey

Yesterday I drove from Reynosa to Monterrey. It would have been about a 2-hour drive, but without a GPS, and Mexico’s lacking road signs, I got lost in Reynosa, and again in Monterrey. But this is part of the adventure, right?

Today on my way from the hotel to where I would be working, I saw something new for me. A train engine. Coming straight at me down the road.

It wasn’t going fast, but it took me completely off guard. I wish I could have taken a photo, but I had the choice between rummaging for a camera, or having the chance to tell you this story.

I suppose to the locals it’s a normal thing to have a railroad track run neither parallel nor perpendicular to, but rather directly down the center of the road, and in opposition to traffic, for a full city block.