search

ScienceCommons / curate_science

Transparency & credibility curation products for all research stakeholders.
https://CurateScience.org
MIT License
13 stars 6 forks source link

Add API documentation #132

Open louispotok opened 4 years ago

louispotok commented 4 years ago

Hello! I'm just discovering Curate Science, and I'm interested in building a small application on top of the API. This issue suggests improvements to the API documentation. If supporting the API is not a priority, I think the minimum would be to say that clearly somewhere in the documentation, at least. And please let me know if there's a better place to start this conversation!

The FAQ says the data is "accessible via an open API (see our GitHub repo for details)" but the repo itself doesn't have any documentation or links to documentation as far as I can see.

Given the info that the project uses the Django REST framework, I was able to figure out the URL for the autogenerated docs here, which are a great start.

Given that the API is mentioned on the website, I think it would make sense to add an API section to the README, and perhaps more about it in the main FAQ as well. That would be most helpful if it included:

  1. A link to the autogenerated docs, or any other documentation that might be available.
  2. A statement about the current status of the API (is it supported, is it expected to work, any known issues etc)
  3. Info on where to ask additional questions (if appropriate).

And then, maybe this deserves a followup issue since I suppose it would be a longer project, but depending on the degree to which you intend to support the API, more documentation about the specific options (either maintained as text, or as part of the autogenerated docs) would be great as well. For example, using the docs I was able to list articles by running a GET request to https://curatescience.org/api/articles/. But looking at the network calls on this page, I see the following request being made: https://curatescience.org/api/articles/?ordering=created&page_size=10&transparency=open_code&transparency=open_data&transparency=open_materials

AFAICT there is no way for an API developer to see all these options or know what they mean without digging into the codebase itself. I would have expected all the possible options to be described in the documentation -- it's possible I'm missing something, though!

Anyway, hope this was helpful. Happy to contribute on some of this as well to the extent possible.

eplebel commented 4 years ago

thanks for the issue report @louispotok!

indeed, our API documentation is very poor, and this is unfortunate. this is due to our currently limited software engineering budget. but based on your useful feedback, i will soon at least improve the situation as per some of your recommendations.

and great to hear you're interested in building a small application on top of our API, i'm very curious to know more about the nature of this application.

and it's even more exciting that you're willing to make some code contributions. i will follow-up over email very soon (at the email address i found at https://louispotok.com/about/), and thanks again for your feedback!