[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 [127.0.0.1]) 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-Level:
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 ([12.22.58.30]) by localhost (ietfa.amsl.com [127.0.0.1]) (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 [127.0.0.1]) 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: /meeting/(?P\d+).json$' 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": "" } href Canonical URL of this object. agenda_href URL for the official agenda. break_area 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 returned. The result of this call, if successful, is the updated JSON of the meeting. POST method. Identical at present to the PUT method. -- Michael Richardson <mcr+IETF@sandelman.ca>, Sandelman Software Works
- [Tools-discuss] RESTful API style guide Michael Richardson
- Re: [Tools-discuss] RESTful API style guide Martin Thomson
- Re: [Tools-discuss] RESTful API style guide Ole Laursen
- Re: [Tools-discuss] RESTful API style guide Tom Pusateri
- Re: [Tools-discuss] RESTful API style guide Michael Richardson
- Re: [Tools-discuss] RESTful API style guide Ole Laursen
- Re: [Tools-discuss] RESTful API style guide Ole Laursen
- Re: [Tools-discuss] RESTful API style guide Michael Richardson
- Re: [Tools-discuss] RESTful API style guide Michael Richardson
- Re: [Tools-discuss] RESTful API style guide Ole Laursen
- Re: [Tools-discuss] RESTful API style guide Carsten Bormann
- Re: [Tools-discuss] RESTful API style guide Nico Williams
- Re: [Tools-discuss] RESTful API style guide Nico Williams
- Re: [Tools-discuss] RESTful API style guide Carsten Bormann
- Re: [Tools-discuss] RESTful API style guide Michael Richardson
- Re: [Tools-discuss] RESTful API style guide Ole Laursen