Output Translation

grep | cut | sort | uniq

Author: Charlie

Q&A on our .Gov to .Com Workshop

We’re hosting a workshop with CustomInk and FluidHire to reach out to tech workers in the federal IT space.  We think a lot of them would be happier working in DC’s busy commercial tech scene, especially with the sequester.  Here’s a quick summary:


The event is tomorrow night, sign up here: http://govtocom.eventbrite.com/

URL Design for RESTful Web Services

This is a cross-post of a guest post I did for APIUX.  Click here for the original..

URL design discussions for RESTful web services often degrade into debates over pluralization and parameter names. There are a couple of principles I like to use to keep things simple.

1) Using your API should feel like using a filesystem

  • Endpoints used to create, list, and search for entities should look like directories, e.g. /users
  • Use a plural noun so it feels like a directory of users, not a user controller
  • Endpoints used to read, update, and delete individual entities should look like files, e.g. /users/charlie

2) All calls to a given endpoint should return the same type

  • Either apples, or oranges, or a list of oranges, don’t mix them up
  • File-looking endpoints should return individual entities
  • Directory-looking endpoints should return lists of entities

We may be bikeshedding here but I think your API will be more intuitive to newcomers if you model it this way.

  • Consistent response type per endpoint simplifies deserialization for clients, no switching needed
  • Once you agree on a contract it’s easy to mock up with static files on a server
  • Clients can start working with your mockup before your code is finished

Example Operations on Endpoints that look like Files


GET /users/charlie
200 OK
{username: charlie, state: VA}


PUT|PATCH /users/charlie


DELETE /users/charlie

Example Operations on Endpoints that Look Like Directories


GET /users?start=40&count=20
200 OK
[{username: charlie, state: VA}, ...]


GET /users?q=cha


POST /users
Location: /users/charlie

Directory endpoints are supposed to return lists (or nothing).  So send back a pointer to the new user record, rather than the user data itself.

POST /users/charlie

Also ok IFF you allow clients to generate entity ids

Serious Bikeshedding

Here’s other stuff I like:

Use a filename extension instead of the Accept header to express the response format:


  • Not pure REST but it makes your API easier for devs to poke with curl and the browser. Easier to use means better adoption!
  • Friendlier on stupid caches that improperly handle headers since the endpoint always sends back the same bytes (within the ttl)
  • You can use .html (or no extension) to request the web representation and serve your API and web views with the same controller logic (though this can turn into a rabbit hole)

Another vote against the Accept header: version your endpoints in the URL, at web-application level:


  • feeds.war is the webapp and 1.0 is the version of the released artifact (which is 1.0.3 internally)
  • Version numbers should correspond to deployable artifacts so they’re easier to manage
  • You’ll need to keep old versions online in real-world use cases

Dropwizard has a nice model for organizing your projects.

Some javascript/flash API consumers will pressure you to add a suppress_response_codes parameter and always send them a 200. You’ll hate it but will end up giving in (just wait).

  • You’ll need to define a standard error response envelope that they can switch on to check for errors and extract the reason. It will get messy for them and they will lose a lot of the benefits of this design.
  • Anyone have better ideas here?

Business idea: Rental food truck

Having your own restaurant is a romantic idea but it’s a lot of work and a risky proposition.  Food trucks are all the rage these days.  Wouldn’t it be nice to rent one for a weekend so you can have the experience and keep your day job? It would be a fun thing to try for a couple of days, even if you don’t make your money back.

The concept is to set up a white-label food truck with some basic restaurant equipment and rent it out for a week or weekend at a time.  Would-be restauranteurs create their own theme and menu, which are displayed on screens on the outside of the truck.  They buy all the food, do all of the cooking and keep all of the sales.  You can occasionally hire celebrity chefs to man the truck to build a social media following.  Use that channel to promote the truck for regular renters to give them a fighting chance.

Say it takes $30-40k to get a truck and set it up with a fridge, grill, fryer and some other basic equipment (lightly used).  If you can rent it out at $1000 for a week or weekend and get it 50% booked, you’ll make your money back in a year assuming 20% to cover maintenance, insurance and fuel.

Open issues:

  • Liability
  • Licensing
  • Quality control

Will it work?

String Gauge For Schecter Elite-5 Basses

This is kind of a note-to-self – Schecter Elite 5-string basses need extra long strings, I tried searching for a part number but google couldn’t find one.  So I called Schecter and Sergio told me:

Your instrument was factory strung with D’Addario EXP170-5SL strings.  The individual string gauges (from low to high) are:

B.-130  E-.100  A-.080  D-.065  G-.045

So there, now google knows.  thanks Sergio!

Finally finished three day croissant recipe

These had better be good. Never doing this again.

My expensive pile of firewood is finally starting to resemble furniture

I dry fit the case and cut the racks for the bottles and glasses. And I measured once and cut twice and paid the price. Otoh, spanish cedar smells sooo good, they should bottle that stuff.

3D model of the cabinet I’m building

I think I only started this project as an excuse to play in solidworks again. If you don’t have a space navigator you need one, trust me: http://www.3dconnexion.com/products/spacenavigator.html


© 2024 Output Translation

Theme by Anders NorenUp ↑