Until recently, if you wanted to know what REST APIs were available in the Open edX platform, you’d have to spin up an instance and then look at the api-docs/ endpoint for your instance to see what was available to you. Starting yesterday, we’ve started publishing all the known REST endpoints for the edx-platform code base to the https://docs.openedx.org site!
This document is auto generated from the code and related doc strings so in a lot of cases it’s pretty incomplete. This is hopefully just a starting point and now that people can see the docs, it will be easier to find gaps and to help improve the documentation by making PRs to the code to add the relevant info there.
Any feedback or questions people have about this would be appreciated!
Would it be possible to generate the “Table of Contents” panel on the right hand side of that page, as seen on other pages like Feature Toggles ? And is there some way the endpoints could be grouped by category?
Hey Braden, thanks for the feedback, I’ll look into why the table of contents is not being generated, I’m using a 3rd party library so it may be a shortcoming of that. I’ll be looking into better grouping and organization of the information as well.
While looking through the API, associating them with the Trichotomy did not seem super useful to me just yet. I think we’re honestly a ways away from being so formal about the APIs. I think once the API exists it should be assumed that people are using it and it should get proper versioning and major version bumps when backwards incompatible changes happen.
A related split that I’ve been seeing in the APIs that I’m hoping we can begin documenting is APIs that only affect the calling user vs APIs that affect other resources (including other users) in the system. I’ve been trying to come up with good names for these but I’m not necessarily happy with what I have:
For the ones that only affect resources related to the calling user:
BFF APIs - Backend for Frontend APIs since they’re often used by MFEs on behalf of the user.
Frontend APIs - Same reason as above
Personal APIs - Since they impact the caller.
For the APIs that affect other resources
System APIs - Since they can impact many resources in the system
Admin APIs - Since the expectation is that you need some level of privilege to use these usually.
Machine-to-machine APIs - Since you could use these to integrate external systems with the Open edX Platform
It may be that this distinction doesn’t matter and would be obvious by what parameters the APIs took and what permissions you needed to use them. So investing in the API documentation would generally make it clear.
I couldn’t continue with this issue this past week for some technical reasons. I would still like to work on reducing the warnings that occur during the building process of the docs.
Though, since the docs are already live, I’m not sure if that is still needed, so I would start working on it if you gave me a go. If it’s not the case, you could still let me know how else I can contribute. I really want to. Thanks.
Currently yes, this is just the edx-platform LMS APIs and even under those, it’s just the ones that have api in the path as a way to filter for things that are more intentionally APIs as opposed to other internal endpoints that use DRF. This is pretty configurable, so I’d love to hear more about any opinions you or others have about this.
Yes, this is currently based off the main branch, I’ll look into backporting this code to Palm but that’s tricky because there were significant changes to the documentation. However, going forward, this doc site will get version with the rest of docs.openedx.org so any future named releases will get versioned docs available.
It’s still useful to get rid of the warnings as they might be occluding some of the docs or other issues that might not be obvious when just looking at the live rendering of the documentation.