Re: [Tools-discuss] RESTful API style guide

Ole Laursen <> Wed, 19 June 2013 15:56 UTC

Return-Path: <>
Received: from localhost (localhost []) by (Postfix) with ESMTP id C137C21F9DAF for <>; Wed, 19 Jun 2013 08:56:44 -0700 (PDT)
X-Virus-Scanned: amavisd-new at
X-Spam-Flag: NO
X-Spam-Score: -2.602
X-Spam-Status: No, score=-2.602 tagged_above=-999 required=5 tests=[AWL=0.375, BAYES_00=-2.599, FM_FORGED_GMAIL=0.622, RCVD_IN_DNSWL_LOW=-1]
Received: from ([]) by localhost ( []) (amavisd-new, port 10024) with ESMTP id x2hINVGIJadj for <>; Wed, 19 Jun 2013 08:56:39 -0700 (PDT)
Received: from ( []) by (Postfix) with ESMTP id A478221F997C for <>; Wed, 19 Jun 2013 08:56:29 -0700 (PDT)
Received: by with SMTP id gd11so3933002vcb.2 for <>; Wed, 19 Jun 2013 08:56:29 -0700 (PDT)
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;; s=20120113; h=mime-version:in-reply-to:references:from:date:message-id:subject:to :content-type:x-gm-message-state; bh=PT9IzNzZeJJ4ytyHC8dgd/gIzoK7pa4B/1Qt5VOofKg=; b=eXoiPVccPqcvfgBSgV4TulhIesOYxqHvQIl2fBghlfbhVt6CXY1Llu+zLnCz/VdxW5 9mGEPPrOZ93ZI24RE1hAj4IownWTEFcHGchwt3D2/013caRHc1O1JNLquqOOofRFeRNZ VFmGdtI9pNVaDli9gToSZSzHWQuOeBX1zT1LAEOv46zymOzNSu8kLJpmJjL/nQYNUJH5 HQu7dl6fnNur5/TP4Bcwt4BwkBdfnfqeJxAavodCjVEybmsuSI3hHgVlMe98hzKWr+Qk TAB4ErnlVNyoN3GTuUD7QLUTiL0lGNn4EPo0Wc4RwvC11qknjBr/wRYJehToT7jqKWWZ jllQ==
X-Received: by with SMTP id ue6mr1170256vec.20.1371657389292; Wed, 19 Jun 2013 08:56:29 -0700 (PDT)
MIME-Version: 1.0
Received: by with HTTP; Wed, 19 Jun 2013 08:56:09 -0700 (PDT)
In-Reply-To: <>
References: <> <> <> <> <>
From: Ole Laursen <>
Date: Wed, 19 Jun 2013 17:56:09 +0200
Message-ID: <>
To: Tools Team Discussion <>
Content-Type: text/plain; charset="ISO-8859-1"
X-Gm-Message-State: ALoCoQlAprVLp2yQ9p+zh7Nx11xVgyo4Cg0qf7WZ3G7bJ9MFhG2zNmto2fQC8IiEyCttNI36yv+f
Subject: Re: [Tools-discuss] RESTful API style guide
X-Mailman-Version: 2.1.12
Precedence: list
List-Id: IETF Tools Discussion <>
List-Unsubscribe: <>, <>
List-Archive: <>
List-Post: <>
List-Help: <>
List-Subscribe: <>, <>
X-List-Received-Date: Wed, 19 Jun 2013 15:56:45 -0000

Hi Michael!

Sorry if I sounded rude, no offense intended, it's just that I
interpreted your first email as if you'd like feedback on the
architecture you've chosen, and that's now turned into a general
discussion about distributed APIs which I find interesting. To me, it
matters that the API doesn't encourage you to do to a lot of
roundtrips - that I think is one of the main lessons of CORBA (and X11
and ...).

Anyway, your comments:

2013/6/19 Michael Richardson <>:
> The list and contents of groups do not change often, they ought to be very
> cachable.   If django supported page caching the way rails does, it could
> be page cached, and therefore served by the apache in front.

AFAIK, Django supports all the forms of caching you'd want. The Django
apps we run at IOLA are behind nginx which has a very simple reverse
proxy cache that you can control simply by the standard caching
headers. I'm pretty sure Apache has the same.

> A search parameter in a GET requires active work to process and reply, and is
> uncachable.

I disagree with that. You don't really need to do more work compared
to what you're doing anyway (i.e. parse the acronym and do a database
query) and all GETs are cacheable by design, at least if you set the
right header.

> Basically you are arguing for:
>         http://foo/groups?name
> vs
>         http://foo/groups/name

I'm arguing for


instead of


The former interface supports everything the latter does, it's more
flexible (just slap another GET parameter on it to implement search),
easier to use if you need more than one, and faster except in the case
where you only need 1. Hence, I don't see much point in doing the
latter interface - you increase your API surface with little value in

Now, don't get me wrong, YMMV, URL paths work really well for HTML and
the web in general. But web documents are big, contain lots of
dependencies, and you usually only want one at the time so it's an
entirely different game.

I'm sorry if my thoughts weren't entirely clear, with this
clarification I'll shut up and get back to work,