On Mon, Jun 1, 2015 at 4:33 PM, Paul Eggleton <paul.eggleton@linux.intel.com> wrote:

On Monday 01 June 2015 14:49:18 Damian, Alexandru wrote:
> On Mon, Jun 1, 2015 at 2:43 PM, Paul Eggleton <paul.eggleton@linux.intel.com
> > wrote:
> >
> > 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@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
>
> This not just internal, but also external support.
>
> > 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?
>
> Yes, it will force us to keep them the same. It will also ease the
> maintaining work.

So what do we do when we need to change the URL structure for the user-facing
side but preserve the API for existing applications?

My plan is to drop support for current API should the URL structure of the toastergui change in radical ways. This is way less drastic than it sounds -

The reasoning is: since this is a REST API, it closely reflects the inner concepts and objects that Toaster manipulates. We're going to radically change the URL structure only if the way that Toaster operates changes dramatically. At that point, maintaining support for a backward-compatible way is going to be a very difficult affair, anyway - we already have the experience with the SimpleUI/separate API that we've just deleted.

Also, if we going to alter the Toaster capabilities in a significant way that impacts the URL structure, the existing code in ToasterGUI application is not going to cut it - at this point, is going to be far easier to add a new application (e.g. toastergui2 ) to hold new code which can expose a different URL structure if needed.

So, in short, if the URL structure needs changing, and we need to support a backward compatible API, the changes are going to happen in a new application.

Cheers,
Paul

--

Paul Eggleton
Intel Open Source Technology Centre

Alex Damian

Yocto Project

SSG / OTC