[zanata-devel] Approach to implementing locale mappings REST endpoint

[David Mason]

----- Original Message -----
> From: "Sean Flanigan" <sflaniga at redhat.com>
> To: "Patrick Huang" <pahuang at redhat.com>, "David Mason" <damason at redhat.com>
> Cc: "zanata-devel" <zanata-devel at redhat.com>
> Sent: Wednesday, 3 December, 2014 12:14:02 PM
> Subject: Re: Approach to implementing locale mappings REST endpoint
> 
> (Moving discussion to zanata-devel...)
> 
> On 2014-12-03 09:39, Patrick Huang wrote:
> > From what I can recall, it is put under "editor" package because
> > it's only used by the new editor at the moment. Since the new
> > editor is still in development therefore it will keep in that
> > package for a while. We *will* be migrating towards new REST api
> > once the new editor and new REST endpoints are stable enough(you
> > may have noticed the new template pattern "project/{projectSlug}"
> > vs the old template pattern "projects/p/{projectSlug} or
> > proj/{projectSlug}").
> 
> Why exactly are we setting up a parallel API hierarchy?  We shouldn't
> need to have three different URL conventions for project resources.

The new API endpoint locations, at least when I was proposing them, were intended to be the first steps in moving to a more sensible API layout - the new endpoints should just be aliases to the old endpoints where appropriate, and the old endpoints should be deprecated when the new version is stable. I don't know anything about the "proj/{projectSlug}" URL structure. I believe most of the discussion around this can be found here: https://github.com/zanata/fake-zanata-server/pull/5


> 
> I didn't create the convention, and /projects/p/{projectSlug} is a
> little ugly, but it does allows us to have both /projects (list of
> projects) and say, /projects/owner/<user> (projects belonging to
> <user>), etc.  In any case, I don't think it's bad enough to justify
> having multiple competing conventions.

The new scheme does not preclude that structure, since the full namespace for project slugs is available after the singular, whereas the plural is used for anything relating to multiple projects:

 - .../projects - summary data of all projects, same as in the old schema.
 - .../projects/{anything} - full namespace available for sub-categories under projects, such as /owner/{username}. Note that "p" is not available here if we want to keep backwards compatibility.
 - .../project/{projectSlug} - data about an individual project
 - .../project/{projectSlug}/{anything} - full namespace available for sub-categories under an individual project, such as locales, versions, single version.
 - .../project/{projectSlug}/versions - summary data about all the versions under a project
 - .../project/{projectSlug}/version/{versionSlug} - data about an individual version

The important thing is not to have ambiguity between identifiers (usernames, slugs, etc.), so I have been careful to ensure that it is always clear from the preceding URL parts what is expected.



> > Once this https://github.com/zanata/zanata-client/pull/37 is merged
> > in, we no longer need an interface in client to make a REST call (no
> > more proxies).
> 
> No more automatically generated proxies, you mean.  It still makes sense
> to define an interface for Java-based clients to share.
> 
> > So it's fine you add new endpoints to it. I am not
> > sure about enunciate documentations. I think once the specific api is
> > stable enough (like this one?) it's worth adding an enunciate
> > interface to api. Moving packages later on won't affect the enunciate
> > doc users.
> 
> But it will affect Java users.  If we have API which we expect to
> change, a common pattern (eg from Eclipse) is to put it into a package
> like org.zanata.rest.service.internal or
> org.zanata.rest.service.experimental, which makes it clear that it might
> change.  (Another option is @Beta tags, as used in Guava and GS
> Collections.)
> 
> However, if we're talking about using this particular bit of API in the
> zanata client, we need to solidify it now, because changing it will
> break our own client.  (Pretty much what David said in his followup email.)
> 
> I suggest we should move at least the required endpoint into
> zanata-common-api/org.zanata.rest.service.
> 
> I think we should err on the side of making all REST APIs visible in
> zanata-common-api by default (eg for use in scripting, integration,
> testing), although if they are not needed by the client we could
> consider putting them into the package org.zanata.rest.service.internal
> initially.
> 
> However, if any of these APIs aren't conforming to the existing URL
> convention, we should fix that before putting them into zanata-common-api.

I agree with most of the above, but here would argue for having all new endpoint URLs conform to the new URL scheme. A gradual transition to the new scheme is a far less risky approach than a big-bang transition later. We have been complaining for years about the existing URL scheme but I doubt there will ever be a good time to schedule a big transition, so we've started fixing it in a way that does not cause any problems for clients of the existing endpoints.


Cheers,

David Mason
Software Engineer
L10n Engineering

Red Hat, Asia-Pacific Pty Ltd
Level 1, 193 North Quay
Brisbane 4000

> > Patrick Huang
> > Senior Software Engineer
> > Engineering - Internationalisation
> > Red Hat
> > 
> > ----- Original Message -----
> >> From: "David Mason" <damason at redhat.com>
> >> To: "zanata-dev-internal" <zanata-dev-internal at redhat.com>
> >> Sent: Wednesday, December 3, 2014 9:28:41 AM
> >> Subject: [zanata-dev-internal] Approach to implementing locale mappings
> >> REST	endpoint
> >>
> >> I am working on sorting out the REST endpoint for locales with mappings,
> >> for
> >> https://bugzilla.redhat.com/show_bug.cgi?id=1156236 and have found the
> >> location of the code a bit odd, so I want to check that I am not about to
> >> do
> >> something inappropriate with it.
> >>
> >> There is an existing endpoint at
> >> {server}/rest/project/{projectSlug}/version/{versionSlug}/locales to get a
> >> list of locales for a version.
> >>
> >> It looks like all the REST endpoints for the editor are not declared in
> >> zanata-api, so they don't get enunciate documentation and are not
> >> available
> >> to clients based on our api library. They are all nested under the
> >> namespace
> >> `org.zanata.rest.editor`, which does not seem ideal to me since the data
> >> they provide is relevant in contexts other than the editor (e.g. this
> >> feature in the client). Does someone know if the new endpoints are
> >> intentionally kept out of the API package? If so, is it because they are
> >> too
> >> volatile at the moment?
> >>
> >> The existing endpoint would be fine for the purpose of this story - it
> >> just
> >> needs an optional field for the mapping, if present. I am loath to add a
> >> new
> >> endpoint when we already have one which is fine and is using the most
> >> appropriate URL pattern, so if there are no objections I will modify the
> >> existing endpoint, move it out of the `editor` package since there is
> >> nothing editor-specific about looking up locales, and move its declaration
> >> to zanata-api.
> >>
> >>
> >> Cheers,
> >>
> >> David Mason
> >> Software Engineer
> >> L10n Engineering
> >>
> >> Red Hat, Asia-Pacific Pty Ltd
> >> Level 1, 193 North Quay
> >> Brisbane 4000
> >>
> >>
> > 
> 
> 
> --
> Sean Flanigan
> 
> Senior Software Engineer
> Engineering - Internationalisation
> Red Hat
> 
>