Gallery 3.1 - REST API revisions
Shad Laws <shad-xpYdmXCiSuZWk0Htik3J/[email protected]> Wed, 5 Jun 2013 18:46:19 +0200
| Newsgroups | gmane.comp.web.gallery.devel |
|---|---|
| Message-ID | <CA+z51A7UHxneFo+chMSHXsRg7i0mp-9-SQS31WZxmtY1TBs_AA@mail.gmail.com> |
--===============8480461485206316515== Content-Type: multipart/alternative; boundary=14dae9c097bc13553604de6af121 --14dae9c097bc13553604de6af121 Content-Type: text/plain; charset=UTF-8 Hey everyone, So, I'm starting to take the deep dive into refactoring the REST API for Gallery 3.1, and I have some thoughts I wanted to toss out there for feedback... Super top-level summary: - Rest resources will change from being helpers (e.g. "helpers/foo_rest.php) to controllers (e.g. "classes/Controller/Rest/Foo.php"). This change is because the main job of a rest resource is to take in a request and generate a response, which is verbatim the definition of controller that K3 uses. All rest resources extend a common Controller_Rest class, which will handle all of the common controller functions (like how to translate between HTTP and REST requests and responses). - Externally, anything that worked in the REST API of Gallery 3.0.x will still work in Gallery 3.1. But... - I'd like to make a few changes (see below for some more details). This would likely change our REST API version number from 3.0 to 3.1, and I can add a "X-Gallery-Api-Deprecated" header to things that are deprecated along with a human-readable description. Alright, now for a few possible changes... ERROR REPORTING --------------------------------- I'd like to be a bit more careful with error reporting. Among the minor wiggles I've noticed so far: - we previously never fired a 405 Method Not Allowed, even for methods other than the 4 RESTful ones. - we previously never set the "Allow" header, either. Should it be the fixed list of four, or should it be tailored for each resource? - most error messages are not translated (e.g. ORM validation errors, "invalid"...), but a couple are (e.g. "Upload failed"). My personal feeling is to be consistent with no translation, which lets REST clients translate fixed messages however they wish. MORE LENIENT HEADER NAMES ------------------------------------------------------ While the API clearly defines "X-Gallery-Request-Method" as the thing to use, there are several other semi-standards (i.e. commonly-used non-standards) out there. Should we be flexible enough to search for them, too? DOCUMENTATION ----------------------------- It might be handy to include in the GET response of each resource a list of possible query parameters along with a human-readable (and non-translated) description as a way of self-documentation... AVAILABLE METHODS/RESOURCES ----------------------------------------- I've been trying to make a nice, consistent map of our current interface, and keep seeing odd asymmetries that are bugging me. My current thought is that there are some methods that should be deprecated entirely and others that should be added/refined. My map of this is still a work in progress - I'll ping y'all once I can present an idea that I don't want to change myself every time I look at it... ORM ---------- While the resources seem like a pretty natural reflection of ORM models, this doesn't really appear to be exploited very much. As a result, it seems like a lot of code is duplicated to do more-or-less the same thing. I'm not sure exactly how yet, but I'd like to make the base Controller_Rest class exploit this fact to simplify things. SUB-REQUESTS ---------------------------- In several places, it looks like the code is redefining the url/entity/members output for a resource in multiple places. This duplication can be eliminated using sub-requests - to get the url/entity/members for a rest resource, just do a sub-request to its rest URL... OUTPUT METHODS -------------------------------- Currently, all methods get JSON-only output with the exception of GET, which can choose HTML or JSONP as well. As Wayne pointed out (see http://galleryproject.org/node/106581), this has some shortcomings. While JSONP is nice for embedding, it's also not very secure (see http://en.wikipedia.org/wiki/JSONP). That's why it's typically only employed for GET responses, although even that can lend itself to hijacking the data elsewhere. It seems that CORS would be a better approach (see http://en.wikipedia.org/wiki/Cross-origin_resource_sharing). It tends to be more secure, can be used on all types of responses (including POST, which was one of Wayne's causes of frustration in the link above), etc. My vote is that we should add CORS, then add a REST admin screen with the option for disabling JSONP entirely. CLEAN URLS ------------------------- Another related non-REST issue is that Apache's mod_rewrite doesn't do well with non-GET methods. This is what led to another of Wayne's head-bashing-against-wall moments in his implementation. K3, however, is savvy enough to understand this exact Apache limitation and ensure that it works a bit more carefully to avoid it. So, when redoing the clean URLs for 3.1, we should use Kohana, not Apache, to fire the 301 redirect. That is, use the [PT] method to route the clean URLs where they need to go, but do *not* use the [R] method to route the dirty URLs to clean ones - instead, use Kohana. Alright, that's the end of my mind dump right now. Thoughts? Take care, Shad --14dae9c097bc13553604de6af121 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable <div dir=3D"ltr">Hey everyone,<div><br></div><div>So, I'm starting to t= ake the deep dive into refactoring the REST API for Gallery 3.1, and I have= some thoughts I wanted to toss out there for feedback...</div><div><br></d= iv> <div>Super top-level summary:</div><div>- Rest resources will change from b= eing helpers (e.g. "helpers/foo_rest.php) to controllers (e.g. "c= lasses/Controller/Rest/Foo.php"). =C2=A0This change is because the mai= n job of a rest resource is to take in a request and generate a response, w= hich is verbatim the definition of controller that K3 uses. =C2=A0All rest = resources extend a common Controller_Rest class, which will handle all of t= he common controller functions (like how to translate between HTTP and REST= requests and responses).</div> <div>- Externally, anything that worked in the REST API of Gallery 3.0.x wi= ll still work in Gallery 3.1. =C2=A0But...<br></div><div>- I'd like to = make a few changes (see below for some more details). =C2=A0This would like= ly change our REST API version number from 3.0 to 3.1, and I can add a &quo= t;X-Gallery-Api-Deprecated" header to things that are deprecated along= with a human-readable description.</div> <div><br></div><div>Alright, now for a few possible changes...</div><div><b= r></div><div>ERROR REPORTING</div><div>---------------------------------</d= iv><div>I'd like to be a bit more careful with error reporting. =C2=A0A= mong the minor wiggles I've noticed so far:</div> <div>- we previously never fired a 405 Method Not Allowed, even for methods= other than the 4 RESTful ones.</div><div>- we previously never set the &qu= ot;Allow" header, either. =C2=A0Should it be the fixed list of four, o= r should it be tailored for each resource?</div> <div>- most error messages are not translated (e.g. ORM validation errors, = "invalid"...), but a couple are (e.g. "Upload failed").= =C2=A0My personal feeling is to be consistent with no translation, which l= ets REST clients translate fixed messages however they wish.</div> <div><br></div><div style>MORE LENIENT HEADER NAMES</div><div style>-------= -----------------------------------------------</div><div style>While the A= PI clearly defines "X-Gallery-Request-Method" as the thing to use= , there are several other semi-standards (i.e. commonly-used non-standards)= out there. =C2=A0Should we be flexible enough to search for them, too?</di= v> <div><br></div><div>DOCUMENTATION</div><div>-----------------------------</= div><div>It might be handy to include in the GET response of each resource = a list of possible query parameters along with a human-readable (and non-tr= anslated) description as a way of self-documentation...</div> <div><br></div><div>AVAILABLE METHODS/RESOURCES</div><div>-----------------= ------------------------</div><div>I've been trying to make a nice, con= sistent map of our current interface, and keep seeing odd asymmetries that = are bugging me. =C2=A0My current thought is that there are some methods tha= t should be deprecated entirely and others that should be added/refined. = =C2=A0My map of this is still a work in progress - I'll ping y'all = once I can present an idea that I don't want to change myself every tim= e I look at it...</div> <div><br></div><div><div>ORM</div><div>----------</div><div>While the resou= rces seem like a pretty natural reflection of ORM models, this doesn't = really appear to be exploited very much. =C2=A0As a result, it seems like a= lot of code is duplicated to do more-or-less the same thing. =C2=A0I'm= not sure exactly how yet, but I'd like to make the base Controller_Res= t class exploit this fact to simplify things.</div> <div><br></div><div>SUB-REQUESTS</div><div>----------------------------</di= v><div>In several places, it looks like the code is redefining the url/enti= ty/members output for a resource in multiple places. =C2=A0This duplication= can be eliminated using sub-requests - to get the url/entity/members for a= rest resource, just do a sub-request to its rest URL...</div> <div><br></div><div style>OUTPUT METHODS</div><div style>------------------= --------------</div><div style>Currently, all methods get JSON-only output = with the exception of GET, which can choose HTML or JSONP as well. =C2=A0As= Wayne pointed out (see=C2=A0<a href=3D"http://galleryproject.org/node/1065= 81">http://galleryproject.org/node/106581</a>), this has some shortcomings.= </div> <div style><br></div><div style>While JSONP is nice for embedding, it's= also not very secure (see=C2=A0<a href=3D"http://en.wikipedia.org/wiki/JSO= NP">http://en.wikipedia.org/wiki/JSONP</a>). =C2=A0That's why it's = typically only employed for GET responses, although even that can lend itse= lf to hijacking the data elsewhere.</div> <div style><br></div><div style>It seems that CORS would be a better approa= ch (see=C2=A0<a href=3D"http://en.wikipedia.org/wiki/Cross-origin_resource_= sharing">http://en.wikipedia.org/wiki/Cross-origin_resource_sharing</a>). = =C2=A0It tends to be more secure, can be used on all types of responses (in= cluding POST, which was one of Wayne's causes of frustration in the lin= k above), etc. =C2=A0My vote is that we should add CORS, then add a REST ad= min screen with the option for disabling JSONP entirely.</div> <div style><br></div><div style>CLEAN URLS</div><div style>----------------= ---------</div><div style>Another related non-REST issue is that Apache'= ;s mod_rewrite doesn't do well with non-GET methods. =C2=A0This is what= led to another of Wayne's head-bashing-against-wall moments in his imp= lementation. =C2=A0K3, however, is savvy enough to understand this exact Ap= ache limitation and ensure that it works a bit more carefully to avoid it. = =C2=A0So, when redoing the clean URLs for 3.1, we should use Kohana, not Ap= ache, to fire the 301 redirect. =C2=A0That is, use the [PT] method to route= the clean URLs where they need to go, but do *not* use the [R] method to r= oute the dirty URLs to clean ones - instead, use Kohana.</div> <div style><br></div><div style>Alright, that's the end of my mind dump= right now. =C2=A0Thoughts?</div><div style><br></div><div style>Take care,= </div><div style>Shad</div> </div></div> --14dae9c097bc13553604de6af121-- --===============8480461485206316515== Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-Disposition: inline ------------------------------------------------------------------------------ How ServiceNow helps IT people transform IT departments: 1. A cloud service to automate IT design, transition and operations 2. Dashboards that offer high-level views of enterprise services 3. A single system of record for all IT processes http://p.sf.net/sfu/servicenow-d2d-j --===============8480461485206316515== Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-Disposition: inline __[ g a l l e r y - d e v e l ]_________________________ [ list info/archive --> http://gallery.sf.net/lists.php ] [ gallery info/FAQ/download --> http://gallery.sf.net ] --===============8480461485206316515==--