Interesting presentation at that link, Sumana; thanks for sharing.
I wonder how the "17 RESTful design concepts" have been selected since I see some major ones missing, such as uniform interface which is quite more RESTful than just "use of HTTP methods":
the MW API, using the HTTP protocol, is accepting POST/GET requests only, but not PUT or DELETE which are part of the uniform interface and rather prefers overloaded POST, and I tend to disagree on "HTTP method override" being a concept really adherent to REST (and that's not only me, there's plenty of literature on the topic supporting this point of view); also "addressability of the resources", another fundament, is missing and our API is not compliant there as well.
I also don't recall "versioned endpoints" being part of any core concept of the REST interface, it seems to me that this deck of slides is a bit imprecise, I also find funny that on slide No. 4 the cover of "RESTful Web Services" by Richardson & Ruby is shown (and is also mentioned at point No. 14 in the references hosted on the page of the full paper) since if the author of this deck would have really recognized it as the "Design guidelines" (the way it is labeled on the deck), then the set of 17 concepts would have been quite different and the ratings of good part of the evaluated API's would have looked different as well.
Overall it looks more like Renzel, as it is common practice when REST is involved, has rated some popular API's against his own understanding of "RESTful", something more near to REST-RPC hybrids.
On Wed, Dec 5, 2012 at 12:59 AM, Sumana Harihareswara <sumanah@wikimedia.org
wrote:
On 11/10/2012 10:23 AM, Federico "Lox" Lucignano wrote:
Handling wikitext in a structured way is an interesting concept, as far
as
I know the team working on the new visual editor (another joint project between the Foundation and Wikia) has built a "parsoid" that does
something
pretty much similar if not the same, that functionality could be exposed
as
an API resource, for more information feel free to drop them an email
(I'm
not sure there's a dedicated mailing list).
That being said, it would be of great interest to get implementation details about the suggestions focusing on the concept that introducing
all
the stated goals/benefits/features would be easy without introducing breaking changes, it's unclear on which basis that assessment is done in the complete absence of technical details (all the documentation
published
so far is made up just of notes listing concepts by name).
On a side note, a simpler, normalized URI schema (URL is too restrictive, in the end REST is not at all about HTTP) would make it possible to also fully exploit OAuth's scopes and add a caching layer such as
Squid/Varnish
maintaining the possibility of purging when needed (that's not really doable when the URI schema is too relaxed).
Just wanted to share the latest status on this from Wikia: https://www.mediawiki.org/wiki/API/REST_proposal/status
"* Finishing evaluating ROA as the underlying REST architecture for the RFC
- Defined the possible format for scope-defining parameters (both
hierarchical and single-level)
- Started identifying the core set of resources to be exposed via the
REST interface, evaluating overloaded Post as a way to allow for 3rd party extensions to a resource
- Completed the outline for a first revision of a protocol-agnostic
router/dispatcher model along with the core set of classes of the API framework
Next step: finalize the first set of docs and move the discussion to a larger group including API designer and Tech leads."
On a completely separate note: I just saw that
http://www.slideshare.net/DominikRenzel/todays-top-restful-services-and-why-... on page 6 grades MediaWiki and other popular applications/services on how RESTful they are.
I'm assuming that red/pink/light green/dark green correlates to "noncompliant/not very compliant/kinda compliant/compliant".
Red: Formal Description Links in Representations Forms in Representations Resource Types Versioned Endpoint Format Selection
Pink: Parameter Sources
Light green: HTTP Method Override
Dark green: Scoping Information Meaningful HTTP Status Use of HTTP Methods
http://www.springerlink.com/index/42307200X642M240.pdf has the full paper in case people want to look at that.
-- Sumana Harihareswara Engineering Community Manager Wikimedia Foundation