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

Unfortunately the issue and the comments were deleted together with the
Github issue tracker.

Therefore let me repeat and extend my issue(s) here.

Best Practice 23 has the title "Follow REST principles when designing
APIs". One therefore expects that the following "principles" are REST
principles and not other suggestions for APIs.

I would suggest that JSON-LD is mentioned as a major hypermedia format.
JSON-LD has already become far more important than XML for the Web.

I would not mention UDDI. It which does not belong to REST and has
become almost irrelevant years ago anyway.

Why not refer to a relevant publicly available text written by Roy T.
Fielding instead of the book by Richardson and Ruby which is not ?

"Design always RESTful APIs using HTTP and good pragmatic REST
principles.": What are "good pragmatic" REST principles?! I suggest to
remove both "good" and "pragmatic".

"There is no unique agreed set of principles for REST APIs, ..."
"... others ... even are still under discussion."

I disagree. There exist companies and people who either did not and do
not bother to understand REST or who who just try to use the good name
of REST to market non-RESTful APIs (often both at the same time). See:
http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

"The following are a set of rules widely adopted so far: ..."

A normal reader will then expect the rules or principles for RESTful
APIs and not general suggestions for APIs. But the following "rules"
have nothing at all to do with REST (which does *not* bother how URIs
look like), they are orthogonal to REST:

"Use hierarchical, readable and technology agnostic Uniform Resource
Identifiers (URIs) to address resources in a consisten way."

"Use the URI path to convey your Resources and Collections model."

"Use nouns but no verbs (except for Controllers that does not involve
resources)." (?What does that mean?)

"Simplify associations. Use query parameters to hide complexity and
provide filtering, sorting, field selection and paging for collections."

And then finally there is this rule:

"Version your API. Never release an API without a version and make the
version mandatory."

The last one is essentially in contradiction to REST. A good(!) RESTful
API does require versioning.

Cheers,
Andreas


Carlos Iglesias wrote:
> Thanks Newton, I have followed the thread on github with my view on this.
> Please Yaso feel free also to add any comments.
> 
> On 21 January 2015 at 14:46, Newton Calegari <newton@nic.br
> <mailto:newton@nic.br>> wrote:
> 
>     Hi,
> 
> 
>     There is an open issue [1] on Github related to a BP about REST.
> 
>     Andreas Kuckartz, a github user, has commented on Carlos Iglesias’
>     commit [2].
> 
>     And he also created the Issue #80 [1] suggesting to review the BP
>     "Follow REST principles when designing APIs" [3].
> 
>     @Carlos Iglesias, @Yaso, I kindly as you to take a look on this
>     issue and check if you agree or not with it.
> 
>     Thanks,
>     Newton
> 
>     [1] https://github.com/w3c/dwbp/issues/80
> 
>     [2] https://github.com/carlosiglesias/dwbp/commit/bdec0b8426e687d6615b789b17f48ddc5222fb93
>     [3] http://w3c.github.io/dwbp/bp.html#BulkAccess2
> 
> 
> 
> 
> -- 
> ---
> 
> Carlos Iglesias. 
> Internet & Web Consultant.
> +34 687 917 759 
> contact@carlosiglesias.es <mailto:contact@carlosiglesias.es> 
> @carlosiglesias 
> http://es.linkedin.com/in/carlosiglesiasmoro/en

Received on Sunday, 1 February 2015 20:41:28 UTC