Re: [Tools-discuss] RESTful API style guide

Ole Laursen <olau@iola.dk> Wed, 19 June 2013 10:40 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 6AFA121F963C for <tools-discuss@ietfa.amsl.com>; Wed, 19 Jun 2013 03:40:47 -0700 (PDT)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -2.478
X-Spam-Level:
X-Spam-Status: No, score=-2.478 tagged_above=-999 required=5 tests=[AWL=0.499, BAYES_00=-2.599, FM_FORGED_GMAIL=0.622, RCVD_IN_DNSWL_LOW=-1]
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 KqOkF7Bc3WQp for <tools-discuss@ietfa.amsl.com>; Wed, 19 Jun 2013 03:40:40 -0700 (PDT)
Received: from mail-vc0-f176.google.com (mail-vc0-f176.google.com [209.85.220.176]) by ietfa.amsl.com (Postfix) with ESMTP id 902CF21F96EF for <tools-discuss@ietf.org>; Wed, 19 Jun 2013 03:40:32 -0700 (PDT)
Received: by mail-vc0-f176.google.com with SMTP id ha12so3631353vcb.7 for <tools-discuss@ietf.org>; Wed, 19 Jun 2013 03:40:32 -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 :content-type:x-gm-message-state; bh=qBb4BXTlzLeF50PdTfv2j24IAVP8LZrhr8Z68lf+3+0=; b=MQ9xz7Y/tGvIOy8P1AwYBNGMnD+G2jbg3RWMvXRgjQPlkk5IB8QA+0S9p5lcvmmiws ejNCZC+AohWHwmnCTfNfL1XpozCVS4fHyuct6ho+TpNQfOWTPThWHc3d9WfcIOZoscby fOisfVBFbMjI72MxuxtZXtni9S7yEV+9C77tkvaX1D2Nc1+edC/HPAGocXtVuXGL1Bqt 93gUzu3QU+rCYsR5pao6f1vAdyUJ/+utVaBshQENlFiKPvZee5oXo6T748WnjTUMVNVR OZTdxHHVKh65gKEFuY1D7uQ1bs7WsDgaa8o7SWfqtWfaS7fs8Zybo0y5TuYg22MBYRZ6 AgfQ==
X-Received: by 10.52.103.99 with SMTP id fv3mr643198vdb.11.1371638432013; Wed, 19 Jun 2013 03:40:32 -0700 (PDT)
MIME-Version: 1.0
Received: by 10.58.133.71 with HTTP; Wed, 19 Jun 2013 03:40:11 -0700 (PDT)
In-Reply-To: <19511.1371584718@sandelman.ca>
References: <21266.1371520672@sandelman.ca> <CANb2OvJS5dpZ4HZ6T=i3-9Mj1Zn0f9LzH7Qhj2hffzoxKSc5PQ@mail.gmail.com> <19511.1371584718@sandelman.ca>
From: Ole Laursen <olau@iola.dk>
Date: Wed, 19 Jun 2013 12:40:11 +0200
Message-ID: <CANb2OvL2gx7DjD+4+WomaBd2_Qw1RhXS8CNPMLbypsoOuQbm5w@mail.gmail.com>
To: Tools Team Discussion <tools-discuss@ietf.org>
Content-Type: text/plain; charset="ISO-8859-1"
X-Gm-Message-State: ALoCoQmKXxlweMwK6On16+q1XzBSDR4FUXV8jnXxUMqVW8C//Y875j+KWG+VAdBKETtqYjTjiWL8
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 10:40:47 -0000

2013/6/18 Michael Richardson <mcr+ietf@sandelman.ca>:
>
> Thanks for the comments on the substance.
> I wanted to initially just get some comments on the *presentation*

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

Are you going to add this to the trac wiki?


Ole