API / Code

This issue is a broad API roadmap discussion and names no files, tests, or entry points. Start by reviewing the existing code and tests from snap, bluepyemodel, and bbp-workflow, then compare their APIs, repository structures, tooling, and search approaches. The work is not complete until the project agrees on a concrete scope and implementation plan.

Opened to discuss the API side of the matters. Obviously, not all the issues need to be resolved on the spot but these are some of my thoughts and questions of the general road map.

Some points of discussion (non-exhaustive, in no particular order)

1. From which tools APIs will be added
   • snap, bluepyemodel, bbp-workflow, etc
2. Uniform "look-and-feel" (for the lack of a better word)
   • naming of actions/items: e.g., get/fetch/retrieve, search/find/query, register/push, resource/entity/item...
   • should probably have a common/core nexus class for everything and inherit/use that in the domain-specific APIs
   • should we try to have somewhat uniform documentation (e.g., same topics: Introduction, Usage, Examples, API doc, changelog)?
3. Structure of the repository
   • Same as in the in bbp docs "Suites" + common code?
   • what would this mean in terms of existing APIs? divide them if they cover more than one suite?
4. Code style/linting/testing
   • Should decide which tools are used if big differences between existing projects
   • test coverage
   • running tests with live data in nexus
5. Conflicting dependencies, if they exist
   • is anything dependant on a specific version of a library
   • will probably remain to be seen
6. Searching for data
   • search method(s) to use
   • how are search filters input (dictionary, kwargs)
   • do we provide "easy-access-classes", e.g. DetailedCircuitApi().get(species=mouse)
7. First steps
   • I guess, moving the code/tests of different projects to have an overall picture what we are dealing with

Please feel free to add questions issues to the list (I'll update if necessary) as there is stuff missing, for sure.

@jdcourcol , @mgeplf , @DrTaDa , @GianlucaFicarelli , @genric