Re: [Tools-discuss] RESTful API style guide

Ole Laursen <olau@iola.dk> Thu, 20 June 2013 15:55 UTC

Return-Path: <olau@iola.dk>
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 9FE2421F9E32 for <tools-discuss@ietfa.amsl.com>; Thu, 20 Jun 2013 08:55:28 -0700 (PDT)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -1.978
X-Spam-Level:
X-Spam-Status: No, score=-1.978 tagged_above=-999 required=5 tests=[BAYES_00=-2.599, FM_FORGED_GMAIL=0.622, NO_RELAYS=-0.001]
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 Qp5BNWZ+j-4T for <tools-discuss@ietfa.amsl.com>; Thu, 20 Jun 2013 08:55:23 -0700 (PDT)
Received: from mail-ve0-x229.google.com (mail-ve0-x229.google.com [IPv6:2607:f8b0:400c:c01::229]) by ietfa.amsl.com (Postfix) with ESMTP id A5D3121F9E24 for <tools-discuss@ietf.org>; Thu, 20 Jun 2013 08:55:18 -0700 (PDT)
Received: by mail-ve0-f169.google.com with SMTP id m1so5238856ves.28 for <tools-discuss@ietf.org>; Thu, 20 Jun 2013 08:55:17 -0700 (PDT)
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=20120113; h=mime-version:in-reply-to:references:from:date:message-id:subject:to :cc:content-type:x-gm-message-state; bh=Xa8xifQUYHRlv3ozQgS882oOQinXuaVB/E9IVayEMV8=; b=bZ+7LDUq5JptjsJKyrB3l6AkYt0MyzgzoM3IjPuSn/hG8bmScCBKzok8R5IZnNdwlI 47LAW4fayzdkHq1Gt8cl4EDT0+9YJgBl44zRA9swjlZdc6wvonIGvZ5MWz1sXfvFmc7a W4t+InGn4LkxzfLPukvXyE7E97nufQGE+RyOok6vDykzic06W5fX6VuCoMG6FzXnhl+f Kim9D8hvCNf+3lFJSx/84Y/vVUXioaZoYloicDLOaBpU80XMOv9s7iPC+5DZyHN984ia 89FNPWrVDWNSwJpllXBcZt3GdjtKBuJuMOc3pvVnV0xqxdu68K3KoKyOSkICn+aM5E4J ssGw==
X-Received: by 10.221.4.138 with SMTP id oc10mr3167350vcb.26.1371743717386; Thu, 20 Jun 2013 08:55:17 -0700 (PDT)
MIME-Version: 1.0
Received: by 10.58.133.71 with HTTP; Thu, 20 Jun 2013 08:54:57 -0700 (PDT)
In-Reply-To: <3948.1371652267@sandelman.ca>
References: <21266.1371520672@sandelman.ca> <CANb2OvJS5dpZ4HZ6T=i3-9Mj1Zn0f9LzH7Qhj2hffzoxKSc5PQ@mail.gmail.com> <19511.1371584718@sandelman.ca> <CANb2OvL2gx7DjD+4+WomaBd2_Qw1RhXS8CNPMLbypsoOuQbm5w@mail.gmail.com> <3948.1371652267@sandelman.ca>
From: Ole Laursen <olau@iola.dk>
Date: Thu, 20 Jun 2013 17:54:57 +0200
Message-ID: <CANb2OvKGSor0jQunn6638WAcH1eAXKAY0LuoYQqSpSqzFOApSQ@mail.gmail.com>
To: Michael Richardson <mcr+ietf@sandelman.ca>
Content-Type: text/plain; charset=ISO-8859-1
X-Gm-Message-State: ALoCoQndTtygOYkGslSC7cZ+akhB3SHbqkt1mT0EtscQGyQxI38E71lwE7NvIAk1G+sqZ9Y/iB3h
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: Thu, 20 Jun 2013 15:55:29 -0000

2013/6/19 Michael Richardson <mcr+ietf@sandelman.ca>:
> Ole Laursen <olau@iola.dk> wrote:
>     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.

Actually what I meant to suggest was that you delete the JSON you've
put in the document and replace it with the test URL. That way it
can't get out of sync which is likely to happen when people touch
these parts in the years to come.

> I don't propose to document anything that isn't self-evident.

Let me just clarify that I'm suggesting you, to the extent possible,
rename attributes that aren't self-evident. For instance, perhaps
"href" should be renamed to "canonical_url".


Ole