Re: [Tools-discuss] RESTful API style guide

Michael Richardson <mcr+ietf@sandelman.ca> Wed, 19 June 2013 14:32 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 4FC3521F9BFE for <tools-discuss@ietfa.amsl.com>; Wed, 19 Jun 2013 07:32:07 -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 t0FYxKJHvGhi for <tools-discuss@ietfa.amsl.com>; Wed, 19 Jun 2013 07:32:06 -0700 (PDT)
Received: from tuna.sandelman.ca (tuna.sandelman.ca [IPv6:2607:f0b0:f:3::184]) by ietfa.amsl.com (Postfix) with ESMTP id 92DEC21F9BE5 for <tools-discuss@ietf.org>; Wed, 19 Jun 2013 07:32:06 -0700 (PDT)
Received: from sandelman.ca (obiwan.sandelman.ca [IPv6:2607:f0b0:f:2::247]) by tuna.sandelman.ca (Postfix) with ESMTP id 492012017D; Wed, 19 Jun 2013 11:35:49 -0400 (EDT)
Received: by sandelman.ca (Postfix, from userid 179) id 3D4F2A9028; Wed, 19 Jun 2013 10:31:07 -0400 (EDT)
Received: from sandelman.ca (localhost [127.0.0.1]) by sandelman.ca (Postfix) with ESMTP id 25F8CB9081; Wed, 19 Jun 2013 10:31:07 -0400 (EDT)
From: Michael Richardson <mcr+ietf@sandelman.ca>
To: Ole Laursen <olau@iola.dk>
In-Reply-To: <CANb2OvL2gx7DjD+4+WomaBd2_Qw1RhXS8CNPMLbypsoOuQbm5w@mail.gmail.com>
References: <21266.1371520672@sandelman.ca> <CANb2OvJS5dpZ4HZ6T=i3-9Mj1Zn0f9LzH7Qhj2hffzoxKSc5PQ@mail.gmail.com> <19511.1371584718@sandelman.ca> <CANb2OvL2gx7DjD+4+WomaBd2_Qw1RhXS8CNPMLbypsoOuQbm5w@mail.gmail.com>
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: Wed, 19 Jun 2013 10:31:07 -0400
Message-ID: <3948.1371652267@sandelman.ca>
Sender: mcr@sandelman.ca
Cc: Tools Team Discussion <tools-discuss@ietf.org>
Subject: Re: [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: Wed, 19 Jun 2013 14:32:07 -0000

Ole Laursen <olau@iola.dk> wrote:
    >> Thanks for the comments on the substance.  I wanted to initially just
    >> get some comments on the *presentation*

    olau> It seems fine to me, but for the GET part maybe it's easier to just
    olau> refer people to a test URL where they can check the JSON, otherwise
    olau> you risk that it gets out of sync. Ideally the attributes would be
    olau> self-evident from their names in the JSON (or changed so they are),
    olau> but otherwise listing those that need explanation seems fine to me
    olau> (as long as the explanation adds new non-self-evident information
    olau> :).

I agree with adding a test URL, when the test URL is stable and deployed.
I don't propose to document anything that isn't self-evident.

    olau> Are you going to add this to the trac wiki?

Yes, that would make sense. Hmm. so really I should keep it in trac wiki
format.

--
]               Never tell me the odds!                 | ipv6 mesh networks [
]   Michael Richardson, Sandelman Software Works        | network architect  [
]     mcr@sandelman.ca  http://www.sandelman.ca/        |   ruby on rails    [





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