API naming convention

[nleroy917]

Overview and houghts: I am just thinking about all the getters for the PepAgent class. Specifically, how should be name the functions that retrieve both namespaces and projects? PEPhub has many endpoints for retrieving information on singular data or plural data. That is, /pep/geo will give you a nice synopsis of the geo namespace, its projects, and its statistics. Conversely, /pep/geo/GSE123456 will give you a synopsis of that specific project. I.e. it's project configuration, samples information, etc. To this end, there needs to be functionality to retrieve one project, multiple projects, one namespace, or multiple namespaces.

My question and discussion point is this: How do we write the PepAgent API to reflect this?

My idea: We will have getters for both projects and namespaces. Each set of getters will have a plural form or a singular form. This lends us to four functions:

1. get_projects("geo") --> Get all projects in namespace
2. get_project("geo/GSE123456) --> Get this specific project
3. get_namespaces() --> Get all namespaces in the database
4. get_namespace("geo") --> Gzet a specific namespace

This doesn't reflect good API design at least for HTTP servers. E.g.

/api/orders --> get all orders
/api/orders/35 --> get order #35

An alternative: Maybe we could just have two getters? Something like:

Project getter:

• get_project() --> get all projects in database
• get_project("geo") --> get all projects in "geo"
• get_project("geo/GSE123456") --> get specific project There can be limit parameters to limit data returned as well.

Namespace getter:

• get_namespace() --> get all namespaces in database
• get_namespace("geo") --> get specific namespace

[nsheff]

I prefer separating get_project and get_projects, to making get_project() return a list of projects, because that seems illogical to me.

Maybe this would work, though:

get_projects() -> returns all projects get_projects(registry_paths=["geo/GSE123456"]) -> returns the list of projects, which could be just one get_projects(namespace="geo") -> self explanatory

registry_paths would be the first argument, I think.

These seem self explanatory to me. But honestly, I have no problem with the 4-function approach, adding in 'get_project()which would then really just be wrapper aroundget_projects(registry_paths=[""])[0]` to convert from a list to a single entity.

[nleroy917]

I've been working a lot on it, and I think I have it all fleshed out for the most part. I will make a PR soon and @Khoroshevskyi if you could review that'd be great.

[khoroshevskyi]

Ok, I will review it!