Improve API documentation

[Mr0grog]

We just recently began to document the REST API for the database using Swagger in the swagger.yaml file (see #58 for the original work on this). Some things that are missing or could be improved:

• Clear written descriptions of each endpoint and of the various parameters each one can take
• Many endpoints can take query parameters for filtering results or searching, but they aren’t well documented (see Add some querystring filters for pages and versions! #41 for more on this)
• Notes about which endpoints require authentication (and how to authenticate generally using basic auth)
• The swagger document is invalid in a couple of spots (we use .. in some endpoints, which Swagger doesn’t seem to like, and we have optional path parameters). If you can figure out how to format these things so the doc is valid, that would be awesome!

If you think you can make the docs look better or be easier to navigate and read, that would also be wonderful. If you can write way more awesome docs without using Swagger at all, that’s also fine. We want to have docs that make the database API easy to learn and use for a variety of research, archival, and analysis purposes more than we want Swagger :)

[maxtedford]

Hey @Mr0grog, I'm not a first-timer, but if you still need some support on any of these pieces of documentation I'd be happy to take a stab at a couple of them. Thoughts?

[Mr0grog]

Ahhh, I totally missed your comment here, sorry! If you want to work on this, that’d be great. The “first-timer” tag isn’t meant to be just for first timers :)

There’s also a new version of the Swagger/OpenAPI that came out since we opened this issue, so it may also make sense to update to that. I haven’t looked in the details, so I don’t know if it’s a big change or not.

[sabrinagannon]

Hey, I'd like to pick up this issue if it's still relevant to your needs 🙂

[lightandluck]

Hi @sganondorf! It would be wonderful if you could tackle this. I don't maintain this repo, but do help coordinate EDGI's community.

If you want you can join our Slack and join the #webmonitoring channel. You can ping me at @lightandluck there, here, or email lightandluck@gmail.com and I'll help you navigate any problem areas and get pointed in the right direction and people if need be.

Thanks so much for your interest!

[Mr0grog]

Howdy, @sganondorf! Yes, help here would be great. While we’ve made improvements since this issue was originally posted, all the bullet points from the original post still apply. In addition, the Swagger/OpenAPI spec has updated and I don’t think we are using the latest version any more. Lots of options to work on here 😬

I also just realized, when re-reading here, that this issue never says that it’s mostly focused on the swagger.yaml file in the repo root and how it renders on the home page of the server (e.g. https://api-staging.monitoring.envirodatagov.org). Of course, if you have improvements for other docs floating around in the repo, that’d be welcome as well!

The “definition of terms” that @lightandluck recently spruced up in our overview repo might also be helpful as an introduction to draw from here, too.

For a lot of the options that endpoints take, you might have to do a bit of spelunking in the code. If you aren’t familiar with Rails, you’ll want to dig into the app/controllers/api/v0/*_controller.rb files.

Also feel free to ask questions here or in Slack! We’ll try and be as responsive as we can.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed in seven days if no further activity occurs. If it should not be closed, please comment! Thank you for your contributions.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed in seven days if no further activity occurs. If it should not be closed, please comment! Thank you for your contributions.