REST API Documentation

Working Groups Build-Test-Release
1

I am creating this topic so that we can have good documentation for all REST API endpoints which are currently available in the open edX platform.

Where can I find the REST API endpoint for user creation?

I have seen this question very often on the discussion forum and on the slack channels. And yes, we have an endpoint for this.

Normally when anyone lookup for the API for open edX they (or me) end up with this link: https://courses.edx.org/api-docs/. This link has APIs listed but some of the endpoints are missing (for example user_api/v1/account/registration/).

The foundation for the API documentation was laid by @nedbat

  1. REST API docs tooling pull request
  2. Improved API documentation

I have gone through this PR which was merged previously but in open-release/juniper.master some of the changes made with this PR are removed (Don’t know why!).

In the last, I would say that it will be nice if we can have all the REST API endpoints under one roof (centralized).

I think we can start like this:

  • Create new doc which will have endpoint, method, description (if we have), codebase location
  • By codebase location, developers or maintainers will be able to get the required body parameters
  • Then gradually we can add the body parameters and can go on if everything goes well

People, please suggest if you have any good ideas about this.

cc: @regis

2

Thanks for bringing this up. I would love to see more movement on this. I’m personally disappointed that I couldn’t make more progress.

What do you mean by “create new doc”? I’m strongly in favor of putting the words near the code, and using tooling to collect them and publish them. Are you thinking of something different than that?

1 Like
3

Thanks for the detailed info @jramnai!

(For background information: @jramnai came to the meetup of the BTR working group and mentioned this issue. I suggested that I could help fix it himself and get the fix merged upstream.)

What you need to do is to generate a new docs/swagger.yaml file that contains the documentation for the endpoints that you are interested in. To generate this file, run:

make swagger

Or equivalently:

DJANGO_SETTINGS_MODULE=docs.docs_settings python manage.py lms generate_swagger --generator-class=edx_api_doc_tools.ApiSchemaGenerator -o docs/swagger.yaml

Once this file has been generated, it will be converted to human-readable documentation by the following command, which is part of make api-docs-sphinx:

python docs/sw2sphinxopenapi.py docs/swagger.yaml docs/api/gen

So, basically, you need to figure out WHY the /user_api/v1/account/registration endpoint is not included in swagger.yaml, while the /api/user/v1/me is, for instance.

This class is documented in swagger.yaml: https://github.com/edx/edx-platform/blob/2c33fc249de02f0c02da94e67b9a64c0f81c0468/openedx/core/djangoapps/user_api/accounts/views.py#L124
While this one isn’t: https://github.com/edx/edx-platform/blob/2c33fc249de02f0c02da94e67b9a64c0f81c0468/openedx/core/djangoapps/user_authn/views/register.py#L448

To figure out the underlying issue, we need to look at the code of the ApiSchemaGenerator in edx_api_doc_tools.conf_utils: https://github.com/edx/api-doc-tools/blob/589bb566b098a81b9ad8ff4797ff3b42ad77ccb4/edx_api_doc_tools/conf_utils.py#L152

It appears that this generator returns only endpoints which start with “/api”. By setting a breakpoint in the get_endpoints method (with import pdb; pdb.set_trace()) we can observe that “/user_api/v1/account/registration/” is in endpoints, but not in subpoints.

Do you start to see the underlying issue @jramnai? Do you understand how to resolve it?

1 Like
4

No, I am not thinking other than that but by “create new doc” my meaning was to include the remaining endpoints and generate the new doc.

Yes, we need to change the get_endpoints method in such a way that it should return all the API endpoints not only which starts with “/api/” (correct me if I am wrong here)

I will try to come up with a solution.

Thanks for the help @regis.

5

The goal was to only document /api/, and for other endpoints that should be documented, add an “alias” in /api/ so that they would be available in a unified namespace.

6

Does that mean that we should create an alias in urls.py to document the user API?

7

That would be the way to do it, yes.

8

@jramnai Do you see how you can implement this?

9 
url(r'^user_api/v1/account/registration/$', register.RegistrationView.as_view(),
    name="user_api_registration"),
url(r'^api/user_api/v1/account/registration/$', register.RegistrationView.as_view(),
    name="api_registration"), #alias

@regis, do you mean above by “create an alias in urls.py”?

10

Yes, something along those lines. I would also change the name of the deprecated url to something like “user_api_registration_legacy”.
You should do the same for the “user_api/v1/account/login_session/” url.
Please test those changes and see if they work (i.e: modify the swagger.yaml file). If yes, then you should be ready to open a PR.

11

Yes @regis, I am testing the changes. But I think we should not change its name as it is being used in many test cases and here, too.

I tried this with debugger and get_endpoints method is not returning 24 API endpoints 'cause they do not start with /api/. By adding alias we will have registration and login_session API endpoints in the API documentation but what about the rest of endpoints?

API endpoints which do not start with /api/:

'/api-admin/api/v1/api_access_request/',
'/courses/{course_id}/teams/',
'/courses/{course_id}/xblock/{usage_id}/view/{view_name}',
'/courses/yt_video_metadata',
'/create_account',
'/csrf/api/v1/token',
'/notifier_api/v1/users/',
'/notifier_api/v1/users/{id}/',
'/oauth2/login/',
'/support/enrollment/{username_or_email}',
'/support/manage_user/{username_or_email}',
'/verify_student/status/',
'/user_api/v1/account/login_session/',
'/user_api/v1/account/password_reset/',
'/user_api/v1/account/registration/',
'/user_api/v1/forum_roles/{name}/users/',
'/user_api/v1/preferences/time_zones/',
'/user_api/v1/preferences/email_opt_in/',
'/user_api/v1/users/',
'/user_api/v1/users/{id}/',
'/user_api/v1/user_prefs/{id}/',
'/user_api/v1/user_prefs/',
'/zendesk_proxy/v0',
'/zendesk_proxy/v1',

If we do not have any strong reason to keep startswith /api/ condition in get_endpoints method then we should remove it and then it will return all the endpoints. But this will affect the unified namespace.

@nedbat & @regis, let me know your thoughts on above.

12

We want the REST API to become more uniform and disciplined. Insisting on the /api/ namespace is one way to do that. The REST API Conventions clearly indicate using the /api/ namespace.

1 Like
13

I understand. My point was that the new url should have the “user_api_registration” while the older url should be renamed to “user_api_registration_legacy”. That way, all calls to reverse("user_api_registration") will point to the new url – which is good.

As Ned explained, we do want all API urls to start with /api. If you are interested in documenting some of these endpoints, then you can apply the same procedure for those endpoints. All those changes can go in a single pull request.

@jramnai: Does that answer your questions? Do you have what it takes to proceed with opening a PR?

14

@jramnai Did you create a PR? Do you need help?

15

No, @regis. But I will open one by this weekend, was extremely busy this days.

I will let you know if I need any help.

Thanks.

1 Like
16

Hi @regis,

I have opened the PR and added you as reviewer.

Let me know if I have missed anything or done anything wrong.

2 Likes