Add update methods to API

[tmushayahama]

add an update api, specifically

• update_individual
• update_evidence
• update_fact

rather than manipulating class expression directly

Ideally any add_? api should have an accompanying update and remove.

pinging @kltm @cmungall @thomaspd @balhoff

[kltm]

There will be a little more that needs to be added/thought through as there can be (for example) multiple class expressions--updates would need to reference the parts that are to be held (e.g. there can be multiple class expressions per individual) vs the parts to be eliminated.

[goodb]

Shouldn't this issue be listed on the minerva repository? https://github.com/geneontology/minerva/issues I believe that is what @balhoff was asking for, no?

There is some confusing use of terminology here. minerva-requests and bbop-manager-minerva aren't the home of an "API" as I would use that word. They are client libraries that should be simplifying the task of creating requests for the actual API.

It would be useful to pause momentarily, back up a step, and actually document the Minerva API itself. This should make things more clear all around.

[balhoff]

I agree, it would be good to move to minerva. I think @kltm can use the GitHub issue mover (I don't have permission on berkeleybop). And yes, the Minerva API needs documentation!

[kltm]

I would actually disagree. As designed, I believe that the correct course would be to keep minerva with the simpler primitives API and have the client APIs, which already intentionally diverge from what the primitives API offers, supply desired patterns. At the end, all that is desired here is to bundle remove and add operations together, and the client API can and (I believe should) allow for getting closer to the GO-specific use cases as they come up.

[goodb]

The desired goal as I see it is a little higher level. We want to be able to, as a team, be more agile in the process of improving Noctua and related applications moving forward. As @cmungall observes here geneontology/minerva#173 the documentation of the different pieces that must be combined to create the minerva experience is very difficult to follow. As one example, there is actually not a single mention of the minerva-requests api anywhere with the minerva repository. If it is, in fact the one and only "minerva api", that is not a very good start.

I humbly suggest that it would be a good idea to begin to improve this by documenting the low-level server api itself first - as nothing actually exists that does so at all. Working outward from that to the layers on top if it, like the request builder, would be a useful way to organize documentation work. This in turn ought to help lead to a more productive and enjoyable team development experience as everyone involved could have a better chance of seeing why the system is put together the way that it is. This is particularly important here because the patterns employed here are a little unusual. With that clearly in place, the team should be in position to make more rapid progress on improvements to the API(s) involved here and ultimately to the user experience.

[kltm]

Absolutely no argument from me that there should not be improved documentation in minerva for the API--we want to make it as easy as possible for people to create non-JS client libraries for minerva. A good starting point would be to move https://github.com/berkeleybop/bbop-manager-minerva/wiki/MinervaRequestAPI to a new home.
A note to this is that the API that minerva implements and the API presented to the public are a little different as commands are necessarily transformed by barista as a general federation layer. This quirk has led to some confusion about where the public API docs should live. That said, minerva may be the best place to do this, with the proper notation of where the public and implemented APIs differ.

[balhoff]

commands are necessarily transformed by barista as a general federation layer

@kltm is this explained in a doc already somewhere? My knowledge of how Minerva and Barista interact is fairly fuzzy.

[kltm]

Not to drag this conversation too far out of scope of this ticket, but I think the short answer is: "unfortunately, not really; we'll need to work on that as above". The longer answer is that we switched over to the "information injection" by barista about a year in and treated the JS client libraries as the point of documentation; as the client does not see the world this way--just give it the token and the commands requests you want to run--the underlying system ended up having a bit of a dearth of documentation (see problem above). (This also gave us the difference in the naming of the client and response libraries.)