[Toaster] [review-request] adamian/20150515_fix_table_header

[Paul Eggleton]

Hi Alex,

On Friday 29 May 2015 14:58:57 Damian, Alexandru wrote:
> On Thu, May 21, 2015 at 11:25 AM, Michael Wood <michael.g.wood at intel.com>
> wrote:
> > Conflating the web pages and the APIs into a single URL pattern/schema
> > just doesn't make sense to me because:
> > 
> > - We will have pages calling themselves with a different parameter (e.g.
> > the tables pages)
> 
> ​And this is quite ok, since it will return the same data, but in a
> different format. The whole idea of REST is to allow a unique point of
> entry for each resource - so the table data in HTML format and in JSON
> format will be at the same URI.​
> 
> > - This is not how REST frameworks are implemented in any other application
> > I've seen before
> 
> ​I've taken the browsable-api from Django REST framework as model; which
> has the same concept of exposing data in different formats based on a GET
> parameter
> 
> http://www.django-rest-framework.org/topics/browsable-api/​
> 
> > - In the future we may want to version the name-space e.g.
> > /api/1.3/projects/
> 
> And this approach will make it easier - we will only have to port a single
> set of URLs ​and not pairs for JSON and HTML content.
> 
> > - Keeping the API self contained allows for greater future flexibility
> > because it de-couples them from the page structure.
> 
> ​Exactly my point - the HTML page structure is created in templates, while
> the data itself is built in the view context; this approach enforces actual
> encapsulation of data in the context, a issue we confronted in the past.

I'm not sure you guys are talking about the same things. If this API is only 
for internal use by the application itself, fine - but if it's also for 
external applications, we probably don't want to break those external 
applications if we have to change the page URL structure. Unifying the page 
URLs and REST API URLs will force us to keep them the same, right?

> > - REST should be as self documenting as possible. Having to know which
> > URLs support JSON responses isn't helpful.
> 
> ​All REST endpoints (indeed, all URLs) will support JSON formats.​

How long do you expect this re-implementation to take? It seems like so far 
we've merged a partial refactoring which has resulted in breakage, which isn't 
really ideal; how long do you estimate we will be in this state?

Cheers,
Paul

-- 

Paul Eggleton
Intel Open Source Technology Centre