[Tools-discuss] RESTful API style guide

Michael Richardson <mcr+ietf@sandelman.ca> Tue, 18 June 2013 01:58 UTC

Return-Path: <mcr@sandelman.ca>
X-Original-To: tools-discuss@ietfa.amsl.com
Delivered-To: tools-discuss@ietfa.amsl.com
Received: from localhost (localhost []) by ietfa.amsl.com (Postfix) with ESMTP id 14F4821E804E for <tools-discuss@ietfa.amsl.com>; Mon, 17 Jun 2013 18:58:54 -0700 (PDT)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -2.599
X-Spam-Status: No, score=-2.599 tagged_above=-999 required=5 tests=[AWL=0.000, BAYES_00=-2.599]
Received: from mail.ietf.org ([]) by localhost (ietfa.amsl.com []) (amavisd-new, port 10024) with ESMTP id R55QySlT2NvQ for <tools-discuss@ietfa.amsl.com>; Mon, 17 Jun 2013 18:58:53 -0700 (PDT)
Received: from tuna.sandelman.ca (tuna.sandelman.ca [IPv6:2607:f0b0:f:3::184]) by ietfa.amsl.com (Postfix) with ESMTP id E0B7521E8050 for <tools-discuss@ietf.org>; Mon, 17 Jun 2013 18:58:52 -0700 (PDT)
Received: from sandelman.ca (obiwan.sandelman.ca [IPv6:2607:f0b0:f:2::247]) by tuna.sandelman.ca (Postfix) with ESMTP id B360320271 for <tools-discuss@ietf.org>; Mon, 17 Jun 2013 22:12:29 -0400 (EDT)
Received: by sandelman.ca (Postfix, from userid 179) id 4D6E863A7C; Mon, 17 Jun 2013 21:57:52 -0400 (EDT)
Received: from sandelman.ca (localhost []) by sandelman.ca (Postfix) with ESMTP id 3E3D763732 for <tools-discuss@ietf.org>; Mon, 17 Jun 2013 21:57:52 -0400 (EDT)
From: Michael Richardson <mcr+ietf@sandelman.ca>
To: tools-discuss@ietf.org
X-Mailer: MH-E 8.2; nmh 1.3-dev; GNU Emacs 23.4.1
X-Face: $\n1pF)h^`}$H>Hk{L"x@)JS7<%Az}5RyS@k9X%29-lHB$Ti.V>2bi.~ehC0; <'$9xN5Ub# z!G,p`nR&p7Fz@^UXIn156S8.~^@MJ*mMsD7=QFeq%AL4m<nPbLgmtKK-5dC@#:k
MIME-Version: 1.0
Content-Type: multipart/signed; boundary="=-=-="; micalg="pgp-sha1"; protocol="application/pgp-signature"
Date: Mon, 17 Jun 2013 21:57:52 -0400
Message-ID: <21266.1371520672@sandelman.ca>
Sender: mcr@sandelman.ca
Subject: [Tools-discuss] RESTful API style guide
X-BeenThere: tools-discuss@ietf.org
X-Mailman-Version: 2.1.12
Precedence: list
List-Id: IETF Tools Discussion <tools-discuss.ietf.org>
List-Unsubscribe: <https://www.ietf.org/mailman/options/tools-discuss>, <mailto:tools-discuss-request@ietf.org?subject=unsubscribe>
List-Archive: <http://www.ietf.org/mail-archive/web/tools-discuss>
List-Post: <mailto:tools-discuss@ietf.org>
List-Help: <mailto:tools-discuss-request@ietf.org?subject=help>
List-Subscribe: <https://www.ietf.org/mailman/listinfo/tools-discuss>, <mailto:tools-discuss-request@ietf.org?subject=subscribe>
X-List-Received-Date: Tue, 18 Jun 2013 01:58:54 -0000

As part of the Agenda Tool work, a number of JSON API calls have been
created.  I have started writing some document for them, at least to have
a list of what is there.  There are a number of inconsistencies in the API,
some of which I know how I want to fix, and some which I do not...

I'm writing it in markdown, although I found that neither the perl nor python
markdown converter seems to deal properly with code samples indented by 4
spaces.  Any suggestions on a better tool chain?

Once I have written up what there is, I will be very interested in what parts
are just broken.  To whet your appetite, the Agenda Tool loads many group
descriptions like:

[17/Jun/2013 18:04:50] "GET /group/splices.json HTTP/1.1" 200 531
[17/Jun/2013 18:04:50] "GET /group/raiarea.json HTTP/1.1" 200 378
[17/Jun/2013 18:04:50] "GET /group/6lowpan.json HTTP/1.1" 200 554
[17/Jun/2013 18:04:50] "GET /group/autoconf.json HTTP/1.1" 200 620
[17/Jun/2013 18:04:50] "GET /group/tsvarea.json HTTP/1.1" 200 346
[17/Jun/2013 18:04:50] "GET /group/hip.json HTTP/1.1" 200 559
[17/Jun/2013 18:04:50] "GET /group/mip4.json HTTP/1.1" 200 530

This is just *TOO SLOW*.  Too many small requests.  (I assume the browser has
a 1.1-persistent session open, but I haven't checked actually).
I'd like to replace it with:
    GET /groups.json
returning an array of groups.  Does this make sense, architecturally?

Any suggestions on things to include, not include, in the API template?

Here is the rough draft of the first entry:


   Methods supported: GET, PUT, POST.

  GET method.

   Returns JSON description of the meeting.
        "agenda_href": "http://thesiteurl/meeting/83/agendas/mtg:83.json",
        "break_area": "Hall Maillot A",
        "city": "Paris",
        "country": "FR",
        "date": "2012-03-25",
        "href": "http://thesiteurl/meeting/83.json",
        "name": "83",
        "reg_area": "Hall Maillot A",
        "submission_correction_date": "2012-05-16",
        "submission_cut_off_date": "2012-04-27",
        "submission_start_date": "2011-12-26",
        "time_zone": "Europe/Paris",
        "venue_name": "",
        "venus_addr": ""


   Canonical URL of this object.


   URL for the official agenda.


   What room are the breaks in.

  PUT method.

   Accepts JSON or "application/x-www-form-urlencoded" dictionary. Accepts
   one argument which is the name of the agenda that should become
   official. The special name "None" or an empty string will set the
   agenda empty.

   This call must be authenticated by a user with secretariat role, and
   the agenda must be already marked public, or an HTTP 406 will be

   The result of this call, if successful, is the updated JSON of the

  POST method.

   Identical at present to the PUT method.

Michael Richardson <mcr+IETF@sandelman.ca>, Sandelman Software Works