Re: [Tools-discuss] RESTful API style guide

[Ole Laursen <[e-mail]>]

2013/6/19 Michael Richardson <[e-mail]>:
> Ole Laursen <[e-mail]> 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