This will help some of @mschor's work for an eventual chatbot plus it will address some of our past requests such as #1176.
Currently our API and CGI code, while publicly accessible is meant more for internal use and client/server communication than public use. I initially teased the idea of having a separate "gEAR-api" repo, but I think the easier approach would be to have a separate "public" directory inside our "api" directory to isolate this code (under a api/public/<entity> route).
The easiest way I see implementing this is having the public API call our existing API/CGI routes, accepting the JSON response results, and curating and extending them in some way. This will help us avoid duplicating server-side code as well as let us pass more RESTful API things, such as links to other allowed/relevant API functions. I do not believe this public API will need to replace the current API/CGI calls in the gEAR web site. Instead it should be more of use to users who want to search for various entities, such as datasets, and perform actions on those entities with close adherence to RESTful naming conventions.
It is also worth noting that our standard access levels for the entities being retrieved will be respected. And the public API should be a curated list of what should be accessed, not a layer over the entire existing server-side code.... users should not be able to delete datasets from the public API for instance.
The list of accessible entities and actions will be fluid, especially as @mschor's work gets underway, but here is what I am thinking of right now:
- datasets (for this list, I'm combining plural and singular nouns)
- search
- get metadata
- download
- gene lists
- search
- get metadata
- download
- dataset collections
- projection
- displays
- get configuration
- set as default (I can see any "update" functions as not being implemented)
- plots
- create plot
- Returns either our standard plotting output, or a native serialization of the plot object (i.e. Plotly Figure, or Matplotlib Figure objects)
- various permalink building
- Currently datasets, collections, and gene lists have ways to generate permalinks, but it's restricted to just that entity. To combine entities and add options, you have to manaully do it, as well as know the extra options
This will help some of @mschor's work for an eventual chatbot plus it will address some of our past requests such as #1176.
Currently our API and CGI code, while publicly accessible is meant more for internal use and client/server communication than public use. I initially teased the idea of having a separate "gEAR-api" repo, but I think the easier approach would be to have a separate "public" directory inside our "api" directory to isolate this code (under a
api/public/<entity>route).The easiest way I see implementing this is having the public API call our existing API/CGI routes, accepting the JSON response results, and curating and extending them in some way. This will help us avoid duplicating server-side code as well as let us pass more RESTful API things, such as links to other allowed/relevant API functions. I do not believe this public API will need to replace the current API/CGI calls in the gEAR web site. Instead it should be more of use to users who want to search for various entities, such as datasets, and perform actions on those entities with close adherence to RESTful naming conventions.
It is also worth noting that our standard access levels for the entities being retrieved will be respected. And the public API should be a curated list of what should be accessed, not a layer over the entire existing server-side code.... users should not be able to delete datasets from the public API for instance.
The list of accessible entities and actions will be fluid, especially as @mschor's work gets underway, but here is what I am thinking of right now: