General refactoring of Tools & APIs

geneontology / geneontology.github.io

Repository for storing GO documentation, directly available through the general GO site

http://geneontology.org

MIT License

6 stars 10 forks source link

General refactoring of Tools & APIs #285

Open lpalbou opened 3 years ago

lpalbou commented 3 years ago

We have an increased number of tools (GO Ribbon, GO-CAM widget, GO Matrix) and APIs (REST, SPARQL, GOLr) and the website could do a better job at listing them.

Proposals

properly differentiate APIs (services to query data) from Tools (high-level UI to accomplish a function)
in that spirit, rename the markdown page "tool-guide" in "api-guide" to avoid anymore confusion
create a top-level menu either "Tools & APIs" or "Services" to list them and give quick access
ensure each Tool & API is properly listed and documented from the menu and the bottom right card on the main page
for API, ideally provide hands-on (e.g. Jupyter notebooks)

Note

The refactoring of the website should be done once the GO API is refactored, to avoid advertising and teaching users on things that are gonna be deprecated.

suzialeksander commented 3 years ago

In the meantime, I'm not sure all the links are going to the right places: https://geneontology.github.io/docs/tools-guide/#query-go-ontology-and-annotations-with-biolink

The GO BioLink API implementation and its associated swagger documentation are available at http://api.geneontology.org/api

But http://api.geneontology.org/api sends me to a nearly blank page that only says "No API definition provided." If I backtrack to https://api.geneontology.org/ there's a link to Swagger UI:http://localhost:8888/api

@lpalbou could you double check these? Or should I at least remove them temporarily if we're going to go ahead and redo this page?

lpalbou commented 3 years ago

Hi suzi:

yes all the links are correct.
for the GO API, I am pretty sure you were trying to access httpS://api.geneontology.org/api and not http://api.geneontology.org/api as it's still working :

I double check and the link on the tool page does redirect to the correct http://api.geneontology.org/api . Long story short, the swagger UI doesn't work in httpS as there was an issue in the Flask/REST library at the time. There is also no easy way to alter the httpS page as this is generated on the fly by Flask/REST.

However, as part of the general refactoring of API, this shouldn't matter as we would have a brand new API.