I am attempting to use the Monarch API for the first time and am finding it rather difficult to learn from the documentation. It is a process of
experimentation rather than following documentation. This is a slow and error-prone approach to programming.
Just for reference, I am trying to query for tuples of (gene, variant, publication) in human, although I would rather learn the API than be told how to answer this question.
The stumbling blocks I have hit so far:
1) The link on https://monarchinitiative.org/ to the API documentation is in a very non-obvious place. Looking under documentation, it is not to be found. On the last try, I find in under "About". Generally "About" pages describe the project as a whole (which the first part does), however it also hides the link to the API. Some of of the entries under Documentation, like "Linking to us" I would expect to find in "About" and either maybe have a "Data" menu for API and download. Also, I notice no page for "citing us". Telling people exactly how one wants to be cited is a great aid getting the citations one wants.
2) So I follow the link "Monarch Web Services and APIs" to https://monarchinitiative.org/page/services. Here I see a nice cartoon of the architecture, which would be good in some other context. However, it is not very helpful in understanding how to use the API. The fact that there is an Owl Loader is not relevant.
5) Then I try the Swagger UI. A Swagger UI is very useful in understanding how to map concepts and a data model to a ReST API. Without understanding concepts and data model, this is a guessing game based on terse descriptions and trying API calls to see what is returned. The documentation in Swagger is very terse and lacks hyperlinks to definitions. What is a compact association? Are the rows zero or one based?
6) It is exciting to see a neo4j database and this might be a great way to answer my questions, however, this leads to needing to understand scigraph, which has the same documentation issues.
How this helps. There is a lot here, however, it has a higher barrier of entry for basic data access. The documentation is more oriented towards Monarch developers than end-users who may not be experts in ontology technology.
I am attempting to use the Monarch API for the first time and am finding it rather difficult to learn from the documentation. It is a process of experimentation rather than following documentation. This is a slow and error-prone approach to programming.
Just for reference, I am trying to query for tuples of (gene, variant, publication) in human, although I would rather learn the API than be told how to answer this question.
The stumbling blocks I have hit so far:
1) The link on https://monarchinitiative.org/ to the API documentation is in a very non-obvious place. Looking under documentation, it is not to be found. On the last try, I find in under "About". Generally "About" pages describe the project as a whole (which the first part does), however it also hides the link to the API. Some of of the entries under Documentation, like "Linking to us" I would expect to find in "About" and either maybe have a "Data" menu for API and download. Also, I notice no page for "citing us". Telling people exactly how one wants to be cited is a great aid getting the citations one wants.
2) So I follow the link "Monarch Web Services and APIs" to https://monarchinitiative.org/page/services. Here I see a nice cartoon of the architecture, which would be good in some other context. However, it is not very helpful in understanding how to use the API. The fact that there is an Owl Loader is not relevant.
3) So I follow the "Monarch BioLink API" https://api.monarchinitiative.org/api/ link. Which links to the github repo and the Swagger UI.
4) So going to https://github.com/biolink/biolink-api, there isn't much in what appears to be user documentation. Some examples, which are not all that useful without understanding the data model and terminology. A client library would be helpful, however, that is a broken link. https://github.com/biolink/biolink-api/blob/master/biolink/biolink-api/wiki/ClientAPIs
5) Then I try the Swagger UI. A Swagger UI is very useful in understanding how to map concepts and a data model to a ReST API. Without understanding concepts and data model, this is a guessing game based on terse descriptions and trying API calls to see what is returned. The documentation in Swagger is very terse and lacks hyperlinks to definitions. What is a compact association? Are the rows zero or one based?
6) It is exciting to see a neo4j database and this might be a great way to answer my questions, however, this leads to needing to understand scigraph, which has the same documentation issues.
How this helps. There is a lot here, however, it has a higher barrier of entry for basic data access. The documentation is more oriented towards Monarch developers than end-users who may not be experts in ontology technology.