Re: [dwbp] BP - URI structure is not relevant for REST

I think Andreas just mistyped “does” for “doesn’t”. 

We probably don’t need to reiterate the versioning best practice here anyway, as it is addressed elsewhere in the data versioning BP. Not surprisingly, I agree with Augusto that versioning should be encouraged, because I don’t believe in assuming one will get it right the first time, and I don’t think versioning an API really goes against the REST principles. (Fielding’s remarks against versioning are about versioning in such a way that resource names change; there are ways to indicate a version that minimize or avoid change to the resource name.) I mentioned versioning APIs in the data versioning BP to prevent confusion between the two types of versioning.

That said, I think we should be very careful about adding detail about how to do REST. We are not here to write best practices for building APIs, and we could get caught up in a huge debate about REST vs. RESTfulness that I don’t think is worthwhile.

I agree that the description of REST should be edited to focus on the basic REST principles as Fielding set them out. While there are many differing opinions about how strictly one must adhere to them, the principles themselves are pretty clear, IMHO. I would avoid mentioning other best practices for building APIs in a BP that is specifically about REST.

-Annette

--
Annette Greiner
NERSC Data and Analytics Services
Lawrence Berkeley National Laboratory
510-495-2935

On Feb 3, 2015, at 9:58 AM, Augusto Herrmann <augusto.herrmann@gmail.com> wrote:

> Where did the issue tracker go? The link is broken.
> 
> I agree with all of Andreas' arguments except for the versioning one. I don't think you meant to write what you just did, as you claim a contradiction and then just reaffirm the very same thing in other words.
> 
> About URIs in RESTful APIs, I think he's right. Readable URIs may be a good thing for developers to use, but that's got nothing to do with REST. The important and essential requirement is that representations carry hyperlinks to every next possible state in the application ("Hypermedia as the Engine of Application State - HATEOAS"). This is easier said than done, and requires careful designing APIs that way.
> 
> On Mon, Feb 2, 2015 at 6:55 AM, Makx Dekkers <mail@makxdekkers.com> wrote:
> 
> If the intention is that HTTP URIs should be used, it's better not to say that URIs should be "technology agnostic".
> 
> HTTP URIs are not technology-agnostic; they rely on the HTTP protocol which is a particular technology, and on DNS which is an implementation of a particular routing technology.
> 
> I would suggest:
> 
> "Use [...] HTTP-based Uniform Resource Identifiers (HTTP URIs) to address resources in a consistent way."
> 
> 
> This is a valid point.
> 
> Best regards,
> Augusto Herrmann
>