Add formal API documentation

misaugstad commented 2 years ago

Brief description of problem/feature

We describe the data in the API in more general terms on the API page, but we are missing a complete spec of what you'll get from each API endpoint. We should be naming every bit of metadata that you get from the API and what exactly that data represents. A lot of it is self-explanatory if you're relatively technical and/or have a decent amount of context about what the Project Sidewalk data looks like. But for someone who has never used the tool, it's unclear what our data represents in some cases.

Potential solution(s)

We could include this data in a table in the HTML for the API page, in a wiki page entry, or even in a CSV that is available for download on the API page.

jonfroehlich commented 2 years ago

@crescendochu and I discussed this today as well. She needs to know exactly how the scoring algorithm works for /v2/access/score/streets as we're relying on it currently for some sidewalk equity analysis.

crescendochu commented 2 years ago

Thank you so much @jonfroehlich! @misaugstad Mikey I know you must be super busy, it would be much appreciated if you could just point me to where to look for it! :)

misaugstad commented 2 years ago

@crescendochu I've now started adding some (temporary) documentation on the API to this wiki page so that I could answer your question and have it available as a resource when we create more permanent documentation! I just added the part assuming we have done clustering already, but I'm assuming that you need the documentation on how we do clustering as well?

jonfroehlich commented 2 years ago

Thanks for making progress on this @misaugstad! Exciting to think about all the ways our API might be used! But we definitely need better docs and this is a step in that direction! 🚀

crescendochu commented 2 years ago

Thank you so much @misaugstad! The wiki page helped a lot!

jonfroehlich commented 2 years ago

I think the first step here is to search for webpages that have nicely formatted and well thought out APIs that we study and then potentially model.

Second, I think we should start writing the API docs in Google Docs, as it's easy to collaborate on and change things. Indeed, I could imagine this being a stand-in for our actual documentation until we have time to switch it over to css/html.

I also think there are some nice frameworks for doing interactive APIs... here's one for Jupyter Notebook (so not relevant to us) but including it here as a reference: https://jupyterbook.org/en/stable/intro.html

misaugstad commented 1 year ago

@jonfroehlich made this slide deck for us to compile some design research on API docs! https://docs.google.com/presentation/d/1ml7b2UHlBek4NcDdrfH-07RoheQ2oZeAV_nO-Hs94cU/edit#slide=id.p

misaugstad commented 1 year ago

I've looked into a bunch of examples of tools that will auto-generate documentation based on an OpenAPI spec yaml or json file. We could use one of these out of the box, which would make things really simple (we can still add our own custom CSS of course). Though each of them has some sort of design decision that I would make differently, so it may be worth it to essentially write our own!

My sense is that if we can generate the documentation using the free/offline version of Swagger, then it's probably best to use Swagger. It's clean, looks nice, and isn't buggy like a lot of the other ones. To me, Swagger looks good enough that it might be worth using it to save us the time generating the HTML ourselves. But I'm totally down to make it myself, using the what I've learned from the different sites and tools.

OpenAPI Explorer

Here's what OpenAPI Explorer looks like; you can choose which city from a dropdown menu in the API Servers section. And it lets you build up an API request by inputting parameters and running it, which is really nice!

Screenshot from 2022-11-28 12-12-21

You can actually test it out yourself by saving the following in an HTML file and opening it in the browser!

<!doctype html>
<html>
  <head>
    <script type="module" src="https://unpkg.com/openapi-explorer@0/dist/browser/openapi-explorer.min.js"></script>
  </head>
  <body>
    <openapi-explorer spec-url="https://raw.githubusercontent.com/ProjectSidewalk/SidewalkWebpage/2754-improve-api-documentation/api-test.yaml" server-url="https://sidewalk-amsterdam-test.cs.washington.edu" show-authentication=false nav-item-spacing="relaxed"> </openapi-explorer>
  </body>
</html>

My main issue with this one is that you have to click on each endpoint in the nav section on the left, it isn't one long document.

OpenAPI Generator

This one has the same issue as above, in that it doesn't display everything at once. It's more stable and has fewer bugs than OpenAPI Explorer, but it doesn't let you build an API request with the UI. Screenshot from 2022-11-28 12-23-44

Bump

Bump will show all the endpoints on one page, but it doesn't let you build a query in the UI, and I don't think that it lets you show the different servers that you have. You can play with it here.

Screenshot from 2022-11-28 12-36-24

Swagger

The Swagger UI looks pretty clean! All the endpoints are shown on one page, with drop-down to test out your own parameters to run queries for each endpoint. You can play around with my test documentation here. It doesn't have a nav section on the left, though! I used the cloud hosted version of Swagger, which costs a lot of money, but they also have an offline version where we should be able to generate the documentation ourselves.

Screenshot from 2022-11-28 12-54-07

misaugstad commented 1 year ago

So I do really like OpenAPI Explorer. One thing to note is that it's actually being actively maintained and improved. I noticed a bug this morning while testing, and the maintainer fixed it in under 45 minutes!

jonfroehlich commented 1 year ago

This is a really great analysis @misaugstad. Thanks for doing this work.

For me, it seems like many of these sites are focused on allowing you to interactively build queries but I guess my own internal thoughts/goals for this page are more like:

Explaining what APIs are available and the goal of each API
Explaining how to use the API (which the above sites sort of do, I suppose...)
Providing multiple examples of using the API with documentation (we kind of do this with our current page but we should expand this and show more examples with different query requests for each API).

And, to me, the layouts that make the most sense are things like the following (albeit I guess all fourare almost the same layout but you can thusly see where my bias is):

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach

https://mmistakes.github.io/minimal-mistakes/docs/configuration/

https://eslint.org/docs/latest/rules/max-classes-per-file

https://learn.microsoft.com/en-us/dotnet/api/system.collections.arraylist?view=net-7.0

All examples from our deck.

The above all follow very standard documentation flows, which makes them easy to understand and use. In contrast, all four of your examples don't use documentation flows that I'm used to, which is maybe why I hesitate... though OpenAPI Explorer maybe matches my internal sense best?

misaugstad commented 1 year ago

Explaining what APIs are available and the goal of each API

I didn't put much effort into actually describing the endpoints well with my examples, but each endpoint has 'summary' and 'description' field, which is where we would do this.

Explaining how to use the API (which the above sites sort of do, I suppose...)

I'm not sure how you imagine this being improved. For a REST API, you use the API by building a URL with an appropriate query string. We can provide an example URL that opens the response in a new tab (which is what we're currently doing on our API page). We could add a section at the top describing how you create a URL to request from an API; Twitter has a whole page devoted to that.

After that, we need to define the parameters so that users know how to build the URL correctly. I think that the examples I showed do that well!

Providing multiple examples of using the API with documentation (we kind of do this with our current page but we should expand this and show more examples with different query requests for each API).

I'm realizing that I didn't make use of the feature of the OpenAPI spec where you can provide examples! I threw one together quickly here, though I would say that it isn't the best format for showing illustrative examples. Screenshot from 2022-11-28 14-32-33

I think that things like the maps that we show are great! And we should show example JSON responses for our other API endpoints, as well as JSON responses (minus the geographic data) for the endpoints where we are showing maps right now.

But I am worried about how busy things would get if we are trying to show multiple example responses for the endpoints.

I thought that the goal of adding more documentation was to more formally define the input parameters and fully describe the outputs. The MDN web docs, at least, do that decently well. Though we will have a ton of output fields, so we will want a more condensed way to display that info!

jonfroehlich commented 1 year ago

I think my primary concern is simply layout and usability. The sites you found are great for like testing out an API, seeing available inputs, and seeing example outputs but aren't really good as documentation sources. Or, at least, vary from the API documentation sources I'm familiar with—but I'm more used to reading programming APIs than like REST APIs.

I thought that the goal of adding more documentation was to more formally define the input parameters and fully describe the outputs.

Yes. I agree! I think your examples do a reasonable job of explaining inputs but not of output fields. We'll want a nice way to do both. Does OpenAPI Explorer support a nice way of documenting and describing output fields?

Also, I understand that you're trying to balance dev effort and maintainability with expected value. It's a hard call.

I'm just having trouble wrapping my brain around Swagger, Bump, OpenAPI, etc. as they aren't what I was expecting and I don't find them that intuitive from a layout/usability perspective. But I'm also not a web dev...

misaugstad commented 1 year ago

Does OpenAPI Explorer support a nice way of documenting and describing output fields?

It does! I hadn't set up that part yet, but it actually doesn't seem half bad. You can define a model for what the output should look like, in addition to examples that fit that model. I'm pretty sure that having multiple named examples is supported as well, though I haven't tested it out yet.

Screenshot from 2022-11-29 14-41-40

I'm just having trouble wrapping my brain around Swagger, Bump, OpenAPI, etc. as they aren't what I was expecting and I don't find them that intuitive from a layout/usability perspective. But I'm also not a web dev...

I get that. In particular, I don't like that we have to include a response code when showing the output from the API! I suppose that this could be useful in the future if we document admin-only API endpoints and such. But at least for now, it messes with the flow a bit.

I do think that part of the issue is that I'm demoing partial examples, so we are missing some examples that would make the docs more clear and familiar. But there are also some differences with what you're used to! I think that my ideal way of documenting our API is somewhere between what you are used to and what I'm demoing. Which is why we are spending our time circling around this:

Also, I understand that you're trying to balance dev effort and maintainability with expected value. It's a hard call.

jonfroehlich commented 1 year ago

Our API also needs to clearly explain all elements returned. Here's a question asked on Slack:

I'm new to working with the Project Sidewalk data (just downloaded first shapefile yesterday)...can anyone point me to documentation of the label types? Everything is self-explanatory, but specifically I'm wondering about "other". I'm assuming "occlusion" is can't see the feature due to car or something in the way and that "signal" is a pedestrian walk signal, but please correct me if I'm wrong.

jonfroehlich commented 1 year ago

In addition, there is outdated information on the API page. A few examples (not a comprehensive list):

We have more label types than this now:

Mikey recently fixed this (I believe) so we don't fail on large queries:

We should completely remove this statement:

misaugstad commented 1 week ago

Bringing this back up to the top: we should at least add a data disctionary for the different APIs to this wiki page: https://github.com/ProjectSidewalk/SidewalkWebpage/wiki/API-Documentation

And then link to it from the API page. And of course make small edits to the API page where information is outdated.

ProjectSidewalk / SidewalkWebpage