Can we bring all API urls under {API_NAME}/v1

[jimallman]

It seems that treemachine and taxomachine currently have most method URLs under the expected v1/, but some methods (those in the non-default plugin?) are shunted off to ext/. Is there some way to bring them all together, short of listing each method name separately with its own ProxyPass directive in the Apache config file?

Here's the current configuration for these APIs:

    <Location /treemachine/v1>
      Order allow,deny
      Allow from all
      ProxyPass  http://localhost:7474/db/data/ext/GoLS/graphdb
      ProxyPassReverse  http://localhost:7474/db/data/ext/GoLS/graphdb
    </Location>

    <Location /treemachine/ext>
      Order allow,deny
      Allow from all
      ProxyPass  http://localhost:7474/db/data/ext
    </Location>

    <Location /taxomachine/v1>
      Order allow,deny
      Allow from all
      ProxyPass  http://localhost:7476/db/data/ext/TNRS/graphdb
      ProxyPassReverse  http://localhost:7476/db/data/ext/TNRS/graphdb
    </Location>

    <Location /taxomachine/ext>
      Order allow,deny
      Allow from all
      ProxyPass  http://localhost:7476/db/data/ext
    </Location>

[chinchliff]

Right, not all of the services are in those "default" classes. In the case of taxomachine, there are two plugin classes with active services: TNRS (which is the "default"), and OTTServices (which contains several non-tnrs services and is likely to contain more), and there could be others. ALL services appear under the native neo4j server-supplied urls at ext//graphdb/.

Services in OTTServices aren't showing up under v1/ because the proxypass doesn't look at that path. I don't suppose we can just add the path /db/data/ext/OTTServices/graphdb path to the v1/ proxypass, can we?

We could also dump all the services for each application into a single class, but I would strongly prefer to avoid that if possible.

On Thu, Jul 17, 2014 at 2:10 PM, Jim Allman notifications@github.com wrote:

It seems that treemachine and taxomachine currently have most method URLs under the expected v1/, but some methods (those in the non-default plugin?) are shunted off to ext/. Is there some way to bring them all together, short of listing each method name separately with its own ProxyPass directive in the Apache config file?

Here's the current configuration for these APIs:

<Location /treemachine/v1>      Order allow,deny      Allow from all      ProxyPass  http://localhost:7474/db/data/ext/GoLS/graphdb      ProxyPassReverse  http://localhost:7474/db/data/ext/GoLS/graphdb    </Location>
<Location /treemachine/ext>      Order allow,deny      Allow from all      ProxyPass  http://localhost:7474/db/data/ext    </Location>
<Location /taxomachine/v1>      Order allow,deny      Allow from all      ProxyPass  http://localhost:7476/db/data/ext/TNRS/graphdb      ProxyPassReverse  http://localhost:7476/db/data/ext/TNRS/graphdb    </Location>
<Location /taxomachine/ext>      Order allow,deny      Allow from all      ProxyPass  http://localhost:7476/db/data/ext    </Location>

— Reply to this email directly or view it on GitHub https://github.com/OpenTreeOfLife/opentree/issues/372.

[jimallman]

Services in OTTServices aren't showing up under v1/ because the proxypass doesn't look at that path. I don't suppose we can just add the path /db/data/ext/OTTServices/graphdb path to the v1/ proxypass, can we?

Understood. I was hoping there might be a trick to "alias" these into a common interface, perhaps a new class that exists only for this purpose?

I'm pretty sure we can't just add multiple paths to a general ProxyPass, since apache has no way to determine which path will resolve successfully. So if the idea above doesn't work, I think we'll need to add a new ProxyPass directive for each new method URL. Not the end of the world, but definitely annoying.

[chinchliff]

Can we allow an individual subdirectory for each plugin class? E.g.

/taxomachine/v1/TNRS/contextQueryForNames /taxomachine/v1/TNRS/autocompleteQuery etc.

(and)

/taxomachine/v1/OTTServices/getTaxonInfo etc.

This would also have the advantage of providing a (minimal) organizational framework. It's likely there will be many individual query methods (e.g. contextQueryForNames), but probably not that many plugin classes (e.g. TNRS)

On Thu, Jul 17, 2014 at 4:02 PM, Jim Allman notifications@github.com wrote:

Services in OTTServices aren't showing up under v1/ because the proxypass doesn't look at that path. I don't suppose we can just add the path /db/data/ext/OTTServices/graphdb path to the v1/ proxypass, can we?

Understood. I was hoping there might be a trick to "alias" these into a common interface, perhaps a new class that exists only for this purpose?

I'm pretty sure we can't just add multiple paths to a general ProxyPass, since apache has no way to determine which path will resolve successfully. So if the idea above doesn't work, I think we'll need to add a new ProxyPass directive for each new method URL. Not the end of the world, but definitely annoying.

— Reply to this email directly or view it on GitHub https://github.com/OpenTreeOfLife/opentree/issues/372#issuecomment-49357444 .

[jar398]

Yes, multiple directories under /v1/ for the various plugin classes is what I had in mind when I set this up.

Given this the choices of /taxomachine/ and /treemachine/ were poor, but so it goes - I felt 'treemachine' was a better 'brand' than GoLS.

Jonathan

On Thu, Jul 17, 2014 at 4:21 PM, Cody Hinchliff notifications@github.com wrote:

Can we allow an individual subdirectory for each plugin class? E.g.

/taxomachine/v1/TNRS/contextQueryForNames /taxomachine/v1/TNRS/autocompleteQuery etc.

(and)

/taxomachine/v1/OTTServices/getTaxonInfo etc.

This would also have the advantage of providing a (minimal) organizational framework. It's likely there will be many individual query methods (e.g. contextQueryForNames), but probably not that many plugin classes (e.g. TNRS)

On Thu, Jul 17, 2014 at 4:02 PM, Jim Allman notifications@github.com wrote:

Services in OTTServices aren't showing up under v1/ because the proxypass doesn't look at that path. I don't suppose we can just add the path /db/data/ext/OTTServices/graphdb path to the v1/ proxypass, can we?

Understood. I was hoping there might be a trick to "alias" these into a common interface, perhaps a new class that exists only for this purpose?

I'm pretty sure we can't just add multiple paths to a general ProxyPass, since apache has no way to determine which path will resolve successfully. So if the idea above doesn't work, I think we'll need to add a new ProxyPass directive for each new method URL. Not the end of the world, but definitely annoying.

— Reply to this email directly or view it on GitHub < https://github.com/OpenTreeOfLife/opentree/issues/372#issuecomment-49357444>

.

— Reply to this email directly or view it on GitHub https://github.com/OpenTreeOfLife/opentree/issues/372#issuecomment-49360139 .

[chinchliff]

We can easily rename classes. GoLS is a prime candidate.

On Thu, Jul 17, 2014 at 9:45 PM, Jonathan A Rees notifications@github.com wrote:

Yes, multiple directories under /v1/ for the various plugin classes is what I had in mind when I set this up.

Given this the choices of /taxomachine/ and /treemachine/ were poor, but so it goes - I felt 'treemachine' was a better 'brand' than GoLS.

Jonathan

On Thu, Jul 17, 2014 at 4:21 PM, Cody Hinchliff notifications@github.com

wrote:

Can we allow an individual subdirectory for each plugin class? E.g.

/taxomachine/v1/TNRS/contextQueryForNames /taxomachine/v1/TNRS/autocompleteQuery etc.

(and)

/taxomachine/v1/OTTServices/getTaxonInfo etc.

This would also have the advantage of providing a (minimal) organizational framework. It's likely there will be many individual query methods (e.g. contextQueryForNames), but probably not that many plugin classes (e.g. TNRS)

On Thu, Jul 17, 2014 at 4:02 PM, Jim Allman notifications@github.com wrote:

Services in OTTServices aren't showing up under v1/ because the proxypass doesn't look at that path. I don't suppose we can just add the path /db/data/ext/OTTServices/graphdb path to the v1/ proxypass, can we?

Understood. I was hoping there might be a trick to "alias" these into a common interface, perhaps a new class that exists only for this purpose?

I'm pretty sure we can't just add multiple paths to a general ProxyPass, since apache has no way to determine which path will resolve successfully. So if the idea above doesn't work, I think we'll need to add a new ProxyPass directive for each new method URL. Not the end of the world, but definitely annoying.

— Reply to this email directly or view it on GitHub <

https://github.com/OpenTreeOfLife/opentree/issues/372#issuecomment-49357444>

.

— Reply to this email directly or view it on GitHub < https://github.com/OpenTreeOfLife/opentree/issues/372#issuecomment-49360139>

.

— Reply to this email directly or view it on GitHub https://github.com/OpenTreeOfLife/opentree/issues/372#issuecomment-49387346 .

[jimallman]

Yes, multiple directories under /v1/ for the various plugin classes is what I had in mind when I set this up.

Given this the choices of /taxomachine/ and /treemachine/ were poor, but so it goes - I felt 'treemachine' was a better 'brand' than GoLS.

I'll be glad to make these modifications to the apache config, if we're clear about what we want from these URLs. As Cody suggested, we could add a subpath for each class, e.g.:

http://api.opentreeoflife.org/taxomachine/v1/OTTServices/getTaxonInfo

... or we could skip the current "root path" and start with /v1/, like so:

http://api.opentreeoflife.org/v1/OTTServices/getTaxonInfo

    <Location /v1/OTTServices>
      Order allow,deny
      Allow from all
      ProxyPass  http://localhost:7476/db/data/ext/OTTServices/graphdb
      ProxyPassReverse  http://localhost:7476/db/data/ext/OTTServices/graphdb
    </Location>

If we take this approach, we could keep the existing classnames and simply use whatever defined paths we'd prefer:

    <Location /v1/ott>
    ...
    <Location /v1/taxo>
    ...
    <Location /v1/taxomachine>
    ...

[chinchliff]

Our current plugin names are below. I have highlighted the ones I think we need to rename.

taxomachine: TNRS - tnrs queries OTTServices - other taxonomy queries, like node lookups GetJSONS - this is obsolete and should just be removed

GetSASJsons - should be renamed, but stephen's tree/taxonomy browing tools use this right now, and will need to be updated PhylografterUpdater - is this even used? if so, the name seems ok. if not, shall we hide it? GoLS - get information and subtrees out of the treemachine db. this is a good candidate for splitting up

oti: QueryServices - run queries on oti IndexServices - index a study. this really should not be public...

[jar398]

As I think about this, the methods are collected into 'interfaces' or 'plugins', and the phylesystem-api has an honorary 'plugin' called 'phylesystem'. Then API calls look like plugin/v1/method. The confusing part is that currently some of the plugins get renamed by apache: GoLS becomes becomes treemachine, and so on. The request seems to be that the apache name and the plugin (Java class) name should be the same, and that's reasonable, although it seems to me that some of the current plugin names (e.g. GoLS) are not that attractive, so we should talk about changes in the plugin names, and naming and case consistency.

It's unfortunate that we have a lower-case plugin in the phylesystem, and camel-case in the neo4j apps. I despise camel case in URLs, but will not push my personal agenda.

Mapping individual methods, as opposed to plugins, in apache is fragile and I think unnecessary.

On Mon, Aug 25, 2014 at 1:22 PM, Cody Hinchliff notifications@github.com wrote:

Our current plugin names are below. I have highlighted the ones I think we need to rename.

taxomachine: TNRS - tnrs queries OTTServices - other taxonomy queries, like node lookups GetJSONS

GetSASJsons - should be renamed, but stephen's tree/taxonomy browing tools use this right now, and will need to be updated PhylografterUpdater - is this even used? if so, the name seems ok. if not, shall we hide it? GoLS - get information and subtrees out of the treemachine db. this is a good candidate for splitting up

oti: QueryServices - run queries on oti IndexServices - index a study. this really should not be public...

— Reply to this email directly or view it on GitHub https://github.com/OpenTreeOfLife/opentree/issues/372#issuecomment-53294980 .

[chinchliff]

I have no issues with renaming the plugin classes to be all lower case. Starting a new email thread with some suggestions.

[josephwb]

Do we have a planned timeline for this? Might as well make argument types consistent while we are at it.

JWB.

On 26 August 2014 11:04, Cody Hinchliff notifications@github.com wrote:

I have no issues with renaming the plugin classes to be all lower case. Starting a new email thread with some suggestions.

— Reply to this email directly or view it on GitHub https://github.com/OpenTreeOfLife/opentree/issues/372#issuecomment-53435278 .

[chinchliff]

Yes, I think we should make argument types consistent in the same pass (for those that have not already been corrected).

We haven't stated an explicit timeline yet, but it won't do much good if it doesn't go live before the hackathon. So, I propose we push these changes to devapi by next Friday (9/5), which would give us the following week (9/8-9/12) to do do bug fixes, etc. before the hackathon begins the week after that.

On Tue, Aug 26, 2014 at 3:11 PM, Joseph W. Brown notifications@github.com wrote:

Do we have a planned timeline for this? Might as well make argument types consistent while we are at it.

JWB.

On 26 August 2014 11:04, Cody Hinchliff notifications@github.com wrote:

I have no issues with renaming the plugin classes to be all lower case. Starting a new email thread with some suggestions.

— Reply to this email directly or view it on GitHub < https://github.com/OpenTreeOfLife/opentree/issues/372#issuecomment-53435278>

.

— Reply to this email directly or view it on GitHub https://github.com/OpenTreeOfLife/opentree/issues/372#issuecomment-53473145 .

[josephwb]

Sounds good to me. JWB.

On 26 August 2014 15:44, Cody Hinchliff notifications@github.com wrote:

Yes, I think we should make argument types consistent in the same pass (for those that have not already been corrected).

We haven't stated an explicit timeline yet, but it won't do much good if it doesn't go live before the hackathon. So, I propose we push these changes to devapi by next Friday (9/5), which would give us the following week (9/8-9/12) to do do bug fixes, etc. before the hackathon begins the week after that.

On Tue, Aug 26, 2014 at 3:11 PM, Joseph W. Brown notifications@github.com

wrote:

Do we have a planned timeline for this? Might as well make argument types consistent while we are at it.

JWB.

On 26 August 2014 11:04, Cody Hinchliff notifications@github.com wrote:

I have no issues with renaming the plugin classes to be all lower case. Starting a new email thread with some suggestions.

— Reply to this email directly or view it on GitHub <

https://github.com/OpenTreeOfLife/opentree/issues/372#issuecomment-53435278>

.

— Reply to this email directly or view it on GitHub < https://github.com/OpenTreeOfLife/opentree/issues/372#issuecomment-53473145>

.

— Reply to this email directly or view it on GitHub https://github.com/OpenTreeOfLife/opentree/issues/372#issuecomment-53477266 .

[jar398]

Any chance we can retain backward compatibility for a while? That would eliminate the risk of breaking existing client code, allowing everyone to transition whenever they like.

[jimallman]

On Aug 26, 2014, at 5:15 PM, Jonathan A Rees notifications@github.com wrote:

Any chance we can retain backward compatibility for a while? That would eliminate the risk of breaking existing client code, allowing everyone to transition whenever they like.

Perhaps this justifies v2 (or v1.1) of the APIs? But that does imply that we’d run v1 versions of all these services alongside the new one.

=jimA=

Jim Allman Interrobang Digital Media http://www.ibang.com/ (919) 649-5760

[chinchliff]

My personal feeling is that it would not be worth it. It would be a nontrivial amount of work/organization given all the proposed changes, and I'm not sure who we would be supporting. To my knowledge, we don't have any clients except our own tools and arbor. In the case of our tools, my impression is that this is basically Jim, treemachine, and phylesystem (maybe?). In the case of arbor engagement is not only very low (I think they use one or two methods), but they will be at the hackathon so we anticipate them using the new methods anyway.

Also, leaving the old methods exposed is likely to result in people using them, no matter how emphatically we tell them not to, and that will produce broken code later. We're about to present our tools to the public for the first time, and we have 40+ people paying attention, which is basically everyone who has an interest at this point. I think we would do ourselves and them a service by providing as clean and simple a system as possible. Which to me, means removing old methods that nobody is/should be using.

I see the benefit--supporting unknown clients who aren't at the hackathon, but I don't think it's worth the drawbacks of added complexity, more prep work for us, more cleanup later, and greater risk of new tools using deprecated methods.

Jim brings up an interesting issue regarding versions. I'm not sure how we will be able to do this in an ongoing way, given the architecture (neo4j plugins). Worth discussing. I don't think the current methods really deserve the "v1" classification. They're more like a beta, and really are not fit for public consumption. I'd be comfortable officially designating the cleaned up versions as v1 though, and supporting backwards compatibility for them in the future.

[chinchliff]

Post-post note: apologies to hackathon folks for the impression that you're all third person here, I forgot that this list also includes all the hackathon participants. You're all of course welcome and encouraged to express thoughts on this topic if you have them! Is anybody using the current apis for anything that would be nontrivial to change? We have proposed changes to the api that will signficantly improve clarity and consistency, but tools using the current apis would need to be adjusted to use the new urls and in some cases argument datatypes might need to be switched as well. If you have such tools, your thoughts are of interest to the decision of whether we support backwards compatibility for our previous (basically "beta") apis.

On Tue, Aug 26, 2014 at 8:37 PM, Cody Hinchliff cody.hinchliff@gmail.com wrote:

My personal feeling is that it would not be worth it. It would be a nontrivial amount of work/organization given all the proposed changes, and I'm not sure who we would be supporting. To my knowledge, we don't have any clients except our own tools and arbor. In the case of our tools, my impression is that this is basically Jim, treemachine, and phylesystem (maybe?). In the case of arbor engagement is not only very low (I think they use one or two methods), but they will be at the hackathon so we anticipate them using the new methods anyway.

Also, leaving the old methods exposed is likely to result in people using them, no matter how emphatically we tell them not to, and that will produce broken code later. We're about to present our tools to the public for the first time, and we have 40+ people paying attention, which is basically everyone who has an interest at this point. I think we would do ourselves and them a service by providing as clean and simple a system as possible. Which to me, means removing old methods that nobody is/should be using.

I see the benefit--supporting unknown clients who aren't at the hackathon, but I don't think it's worth the drawbacks of added complexity, more prep work for us, more cleanup later, and greater risk of new tools using deprecated methods.

Jim brings up an interesting issue regarding versions. I'm not sure how we will be able to do this in an ongoing way, given the architecture (neo4j plugins). Worth discussing. I don't think the current methods really deserve the "v1" classification. They're more like a beta, and really are not fit for public consumption. I'd be comfortable officially designating the cleaned up versions as v1 though, and supporting backwards compatibility for them in the future.

[mtholder]

I guess I don't see what is hard about retaining backward compatibility here, by moving to v2. We can just have thin wrappers that delegate calls with the old names/arguments to the new versions. I'm not sure which datatypes have to change, so perhaps I'm underestimating how much of a pain that it will be.

I think that we need to decide whether we have a versioned API or not. I think we decided in June that we should have versioning (hence the v1 everywhere). I'm definitely on board with that. If that is the case, it seems like we should bump the version number when we make changes that will cause a previously valid call to fail. If we can't support and old version, then we return an error code pointing users to the newer call, but ideally that would be very rare (or preceded by a long period of issuing deprecation warnings in some way).

I have a fair number of wrappers in peyotl. Of course, I do not mind updating them to use the newest versions of the calls. But for chasing down regression bugs (using "git bisect" for example) it is really nice to have backward compatibility for a while at least.

And I second @jar398 's point (on IRC) that it is just good practice to not break things without a good reason.

[chinchliff]

Alright. Chasing down bugs from before the change is a good reason to keep backward compatibility that I hadn't thought of. I'm not adamant about getting rid of the v1/ services. So that's fine, we can figure out how to keep the ones that are needed for that. Regarding Jonathan's point though, I think that there are good reasons for getting rid of outdated services that nobody is using.

There are a bunch of services that are just cruft, leftover from previous eras, which haven't been used for a long time and which aren't going to be used again, such as the getJsons plugin in taxomachine. I'm assuming these can just go.

Regarding versions. Currently, for the neo4j plugins at least, these are assigned at the level of the plugin (a java class) itself. This means all services (the methods of the class) are assigned the same version. This means we can't increment a version for a service without doing it for all the other services in that plugin as well. Is that something we want to be able to do? Can we give every service it's own version number, or is the version supposed to apply to the entire API at once?

Also, only one plugin from each tool has actually been versioned so far:

treemachine/GoLS taxomachine/TNRS oti/QueryServices

So, what do we do about the plugins that haven't been designated v1 yet? This include OTTServices in taxomachine and IndexServices in oti. Will those just start at v2?

Our current urls look like:

treemachine/v1/{service}

but I think we want them to look more like:

treemachine/{plugin}/vN/{service} or treemachine/vN/{plugin}/{service}

But maybe we want something else?

Anyway, I'm kind of tired of all this typing, I think it takes more time than just having a conversation would. Does anybody have time for a short call tomorrow or Friday so we could hash some of this stuff out?

[jimallman]

On Aug 27, 2014, at 9:53 AM, Cody Hinchliff notifications@github.com wrote:

Alright. Chasing down bugs from before the change is a good reason to keep backward compatibility that I hadn't thought of.

We can always deploy a test system with tagged releases of peyotl, treemachine, etc. Wouldn’t that give us a “v1” test environment?

Can we give every service it's own version number, or is the version supposed to apply to the entire API at once?

This is (IMO) the big question. I had originally thought we’d version the whole API family at once, but (as others pointed out) this is unnecessarily disruptive to existing API clients unless we support the old versions as well.

Our current urls look like:

treemachine/v1/{service}

but I think we want them to look more like:

treemachine/{plugin}/vN/{service} or treemachine/vN/{plugin}/{service}

I think the URL design should follow our versioning strategy, so that vN always follows {versioned thing}. So if we’re versioning the whole API family:

vN/treemachine/{plugin}/{service}

And if we’re versioning individual APIs (treemachine vs phylesystem):

treemachine/vN/{plugin}/{service}

And for versioned plugins:

treemachine/{plugin}/vN/{service}

Of course, some of these options will likely be very tricky to implement in neo4j plugins or web2py, respectively. I think it’s going to be hard to avoid some clever routing in Apache and/or web2py, no matter what path we take.

=jimA=

Jim Allman Interrobang Digital Media http://www.ibang.com/ (919) 649-5760

[jar398]

On Wed, Aug 27, 2014 at 9:53 AM, Cody Hinchliff notifications@github.com wrote:

Alright. Chasing down bugs from before the change is a good reason to keep backward compatibility that I hadn't thought of. I'm not adamant about getting rid of the v1/ services. So that's fine, we can figure out how to keep the ones that are needed for that. Regarding Jonathan's point though, I think that there are good reasons for getting rid of outdated services that nobody is using.

I never said we should keep them. I said we should keep them for a transitional period of 1-2 months.

There are a bunch of services that are just cruft, leftover from previous eras, which haven't been used for a long time and which aren't going to be used again, such as the getJsons plugin in taxomachine. I'm assuming these can just go.

We're only talking about the services that are documented at https://github.com/OpenTreeOfLife/opentree/wiki/Open-Tree-of-Life-APIs. The others are assumed unstable.

Regarding versions. Currently, for the neo4j plugins at least, these are assigned at the level of the plugin (a java class) itself. This means all services (the methods of the class) are assigned the same version. This means we can't increment a version for a service without doing it for all the other services in that plugin as well. Is that something we want to be able to do? Can we give every service it's own version number, or is the version supposed to apply to the entire API at once?

To version an individual service just make a new service with a new name.

Also, only one plugin from each tool has actually been versioned so far:

treemachine/GoLS taxomachine/TNRS oti/QueryServices

So, what do we do about the plugins that haven't been designated v1 yet? This include OTTServices in taxomachine and IndexServices in oti. Will those just start at v2?

I think it will be best for users if we talk about version 1 / 2 / 3 of the open tree API. They're not going to want to micromanage versions or update frequently as versions of particular plugins change incompatibly.

Our current urls look like:

treemachine/v1/{service}

but I think we want them to look more like:

treemachine/{plugin}/vN/{service} or treemachine/vN/{plugin}/{service}

But maybe we want something else?

I think we want vN/plugin/service where plugin = treemachine, TNRS, etc. Putting the version number as the first component of the path is the pattern you'll see if you look at other public APIs e.g. http://www.gbif.org/developer/summary .

That plugins belong to the treemachine or taxomachine or OTI neo4j servers is an implementation detail that most people won't care about. We can have a plugin called 'treemachine' if we want, and it and other plugins can be provided by the treemachine server, but the fact the plugin Xyz is provided by the treemachine server doesn't need to be exposed - we can just call it the xyz plugin (vN/xyz/service).

We are not operating in a vacuum, you know - there are a gajillion discussions of API versioning out there and maybe we should do some research.

Remember that versioning the API as a whole doesn't rule out compatible changes such as adding new services or new optional arguments. New components in result objects can also be added if the documentation is written to forewarn that this might happen.

Anyway, I'm kind of tired of all this typing, I think it takes more time than just having a conversation would. Does anybody have time for a short call tomorrow or Friday so we could hash some of this stuff out?

How about Friday at 11?

— Reply to this email directly or view it on GitHub https://github.com/OpenTreeOfLife/opentree/issues/372#issuecomment-53575070 .

[kcranston]

Friday at 11 works for me.

On Wed, Aug 27, 2014 at 10:50 AM, Jonathan A Rees notifications@github.com wrote:

On Wed, Aug 27, 2014 at 9:53 AM, Cody Hinchliff notifications@github.com

wrote:

Alright. Chasing down bugs from before the change is a good reason to keep backward compatibility that I hadn't thought of. I'm not adamant about getting rid of the v1/ services. So that's fine, we can figure out how to keep the ones that are needed for that. Regarding Jonathan's point though, I think that there are good reasons for getting rid of outdated services that nobody is using.

I never said we should keep them. I said we should keep them for a transitional period of 1-2 months.

There are a bunch of services that are just cruft, leftover from previous eras, which haven't been used for a long time and which aren't going to be used again, such as the getJsons plugin in taxomachine. I'm assuming these can just go.

We're only talking about the services that are documented at https://github.com/OpenTreeOfLife/opentree/wiki/Open-Tree-of-Life-APIs. The others are assumed unstable.

Regarding versions. Currently, for the neo4j plugins at least, these are assigned at the level of the plugin (a java class) itself. This means all services (the methods of the class) are assigned the same version. This means we can't increment a version for a service without doing it for all the other services in that plugin as well. Is that something we want to be able to do? Can we give every service it's own version number, or is the version supposed to apply to the entire API at once?

To version an individual service just make a new service with a new name.

Also, only one plugin from each tool has actually been versioned so far:

treemachine/GoLS taxomachine/TNRS oti/QueryServices

So, what do we do about the plugins that haven't been designated v1 yet? This include OTTServices in taxomachine and IndexServices in oti. Will those just start at v2?

I think it will be best for users if we talk about version 1 / 2 / 3 of the open tree API. They're not going to want to micromanage versions or update frequently as versions of particular plugins change incompatibly.

Our current urls look like:

treemachine/v1/{service}

but I think we want them to look more like:

treemachine/{plugin}/vN/{service} or treemachine/vN/{plugin}/{service}

But maybe we want something else?

I think we want vN/plugin/service where plugin = treemachine, TNRS, etc. Putting the version number as the first component of the path is the pattern you'll see if you look at other public APIs e.g. http://www.gbif.org/developer/summary .

That plugins belong to the treemachine or taxomachine or OTI neo4j servers is an implementation detail that most people won't care about. We can have a plugin called 'treemachine' if we want, and it and other plugins can be provided by the treemachine server, but the fact the plugin Xyz is provided by the treemachine server doesn't need to be exposed - we can just call it the xyz plugin (vN/xyz/service).

We are not operating in a vacuum, you know - there are a gajillion discussions of API versioning out there and maybe we should do some research.

Remember that versioning the API as a whole doesn't rule out compatible changes such as adding new services or new optional arguments. New components in result objects can also be added if the documentation is written to forewarn that this might happen.

Anyway, I'm kind of tired of all this typing, I think it takes more time than just having a conversation would. Does anybody have time for a short call tomorrow or Friday so we could hash some of this stuff out?

How about Friday at 11?

— Reply to this email directly or view it on GitHub < https://github.com/OpenTreeOfLife/opentree/issues/372#issuecomment-53575070>

.

— Reply to this email directly or view it on GitHub https://github.com/OpenTreeOfLife/opentree/issues/372#issuecomment-53583722 .

karen.cranston@gmail.com
@kcranstn

[chinchliff]

Me too

On Wednesday, August 27, 2014, Karen Cranston notifications@github.com wrote:

Friday at 11 works for me.

On Wed, Aug 27, 2014 at 10:50 AM, Jonathan A Rees < notifications@github.com javascript:_e(%7B%7D,'cvml','notifications@github.com');> wrote:

On Wed, Aug 27, 2014 at 9:53 AM, Cody Hinchliff < notifications@github.com javascript:_e(%7B%7D,'cvml','notifications@github.com');>

wrote:

Alright. Chasing down bugs from before the change is a good reason to keep backward compatibility that I hadn't thought of. I'm not adamant about getting rid of the v1/ services. So that's fine, we can figure out how to keep the ones that are needed for that. Regarding Jonathan's point though, I think that there are good reasons for getting rid of outdated services that nobody is using.

I never said we should keep them. I said we should keep them for a transitional period of 1-2 months.

There are a bunch of services that are just cruft, leftover from previous eras, which haven't been used for a long time and which aren't going to be used again, such as the getJsons plugin in taxomachine. I'm assuming these can just go.

We're only talking about the services that are documented at https://github.com/OpenTreeOfLife/opentree/wiki/Open-Tree-of-Life-APIs. The others are assumed unstable.

Regarding versions. Currently, for the neo4j plugins at least, these are assigned at the level of the plugin (a java class) itself. This means all services (the methods of the class) are assigned the same version. This means we can't increment a version for a service without doing it for all the other services in that plugin as well. Is that something we want to be able to do? Can we give every service it's own version number, or is the version supposed to apply to the entire API at once?

To version an individual service just make a new service with a new name.

Also, only one plugin from each tool has actually been versioned so far:

treemachine/GoLS taxomachine/TNRS oti/QueryServices

So, what do we do about the plugins that haven't been designated v1 yet? This include OTTServices in taxomachine and IndexServices in oti. Will those just start at v2?

I think it will be best for users if we talk about version 1 / 2 / 3 of the open tree API. They're not going to want to micromanage versions or update frequently as versions of particular plugins change incompatibly.

Our current urls look like:

treemachine/v1/{service}

but I think we want them to look more like:

treemachine/{plugin}/vN/{service} or treemachine/vN/{plugin}/{service}

But maybe we want something else?

I think we want vN/plugin/service where plugin = treemachine, TNRS, etc. Putting the version number as the first component of the path is the pattern you'll see if you look at other public APIs e.g. http://www.gbif.org/developer/summary .

That plugins belong to the treemachine or taxomachine or OTI neo4j servers is an implementation detail that most people won't care about. We can have a plugin called 'treemachine' if we want, and it and other plugins can be provided by the treemachine server, but the fact the plugin Xyz is provided by the treemachine server doesn't need to be exposed - we can just call it the xyz plugin (vN/xyz/service).

We are not operating in a vacuum, you know - there are a gajillion discussions of API versioning out there and maybe we should do some research.

Remember that versioning the API as a whole doesn't rule out compatible changes such as adding new services or new optional arguments. New components in result objects can also be added if the documentation is written to forewarn that this might happen.

Anyway, I'm kind of tired of all this typing, I think it takes more time than just having a conversation would. Does anybody have time for a short call tomorrow or Friday so we could hash some of this stuff out?

How about Friday at 11?

— Reply to this email directly or view it on GitHub <

https://github.com/OpenTreeOfLife/opentree/issues/372#issuecomment-53575070>

.

— Reply to this email directly or view it on GitHub < https://github.com/OpenTreeOfLife/opentree/issues/372#issuecomment-53583722>

.

karen.cranston@gmail.com
<javascript:_e(%7B%7D,'cvml','karen.cranston@gmail.com');>
@kcranstn

— Reply to this email directly or view it on GitHub https://github.com/OpenTreeOfLife/opentree/issues/372#issuecomment-53584190 .

[jimallman]

On Aug 27, 2014, at 10:53 AM, Karen Cranston notifications@github.com wrote:

Friday at 11 works for me.

+1

=jimA=

[mjy]

Just a vote for the "version the family" option, i.e. make the version the first thing there.

http://api.opentreeoflife.org/v1/taxomachine/OTTServices/getTaxonInfo

I'd argue that the public (e.g. those writing wrappers) would be happy if they could update across all "plugins" rather than have to maintain different vS for each plugin? As you note this sacrifices agility for stability, but that's likely a good thing.

[jar398]

Jim, you raised the issue and a lot of work got done on it. Did it get resolved to your satisfaction?

[jimallman]

Thanks for the nudge, closing now. I think we've cleaned this up nicely, esp. the v2 URLs.