- From: Annette Greiner <amgreiner@lbl.gov>
- Date: Sun, 26 Jul 2015 23:53:23 -0700
- To: Andreas Kuckartz <a.kuckartz@ping.de>, Erik Wilde <dret@berkeley.edu>
- Cc: Carlos Iglesias <carlos.iglesias.moro@gmail.com>, Newton Calegari <newton@nic.br>, Data on the Web Best Practices Working Group <public-dwbp-wg@w3.org>, Yaso <yaso@nic.br>
Does anybody have an example of a successful HATEOAS compliant API that does not use versioning? I'm honestly wondering, not trolling here. In order to argue for something as a best practice, it helps to be able to point to successful use. -Annette On Jul 24, 2015, at 6:58 AM, Andreas Kuckartz <a.kuckartz@ping.de> wrote: > Unfortunately neither my mail from 2015-02-01 nor the brief discussion > about it in February 2015 seems to have had an effect on the BP document. > > As stated then I strongly disagree with the content of "Best Practice > 24: Follow REST principles when designing APIs". > > I can offer to provide a more concrete proposal for the content and to > contact Roy T. Fielding to ask him for feedback. But I need some kind of > guarantee that the result then finally will be considered by the WG. > > Cheers, > Andreas > > > Andreas Kuckartz wrote on 2015-02-01: >> 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 Monday, 27 July 2015 06:53:48 UTC