diff --git a/docs/concepts/index.rst b/docs/concepts/index.rst index 01f92503795c..fa4a02125ffa 100644 --- a/docs/concepts/index.rst +++ b/docs/concepts/index.rst @@ -10,3 +10,4 @@ Concepts and Guides frontend/styling frontend/bootstrap frontend/static_assets + rest_apis diff --git a/docs/concepts/rest_apis.rst b/docs/concepts/rest_apis.rst new file mode 100644 index 000000000000..37c8390e60d8 --- /dev/null +++ b/docs/concepts/rest_apis.rst @@ -0,0 +1,32 @@ +edx-platform REST API Concepts +############################## + +APIs in the edx-platform fall into one of two categories. **Personal APIs** +that only let you manipluate resources related to your user (the single user +associated with the OAuth2 Application) or **Machine-to-machine APIs** that +allow you to manipulate other users and system resources so long as the user +associated with the OAuth2 application has the permissions to do so. + +The best way to interact with the APIs is to get a JWT Token associated with a +user and then pass that to the server as a part of the request header. + +You can get a JWT one of two ways, one is to exchange the username and password +for a user to get their JWT, and the other is to get a JWT associated with an +OAuth2 Application (the application is associated with your user)that allow you +to manipulate other users and system resources so long as the user associated +with the OAuth2 application has the permissions to do so. + +The best way to interact with the APIs is to get a JWT Token associated with a +user and then pass that to the server as a part of the request header. + +You can get a JWT one of two ways, one is to exchange the username and password +for a user to get their JWT, and the other is to get a JWT associated with an +OAuth2 Application (the application is associated with your user). + +JWTs by default expire every hour so when they expire you'll have to get a new +one before you can call the API again. + +.. seealso:: + + * :doc:`/how-tos/use_the_api` + * `OAuth2, JWT and Mobile `_ diff --git a/docs/how-tos/use_the_api.rst b/docs/how-tos/use_the_api.rst new file mode 100644 index 000000000000..c887911f20a8 --- /dev/null +++ b/docs/how-tos/use_the_api.rst @@ -0,0 +1,86 @@ +How To Use the REST API +####################### + +.. How-tos should have a short introduction sentence that captures the user's goal and introduces the steps. + +This how-to will help get setup to be able to make aunthenticated requests to +the edx-platform REST API. + +Assumptions +*********** + +.. This section should contain a bulleted list of assumptions you have of the + person who is following the How-to. The assumptions may link to other + how-tos if possible. + +* You have access to the edx-platform Django Admin (``/admin``) Panel. + +* You have a user that you want to make the rest calls as (``UserA``). + +* You are familiar with `the basics of HTTP and Rest`_ + +* For the purposes of this tutorial we'll assume your LMS is located at + https://lms.example.com + +.. _the basics of HTTP and Rest: https://code.tutsplus.com/a-beginners-guide-to-http-and-rest--net-16340t + +Steps +***** + +.. A task should have 3 - 7 steps. Tasks with more should be broken down into digestible chunks. + +#. Go to https://lms.example.com/admin/oauth2_provider/application/ + +#. Click :guilabel:`Add Application` + +#. Choose "UserA" for the user. + +#. Choose ``Confidential`` Client Type + +#. Choose "Client Credentials" for the Authorization Grant Type + +#. Set a name for your application. + +#. Save the ``client_id`` and ``client_secret``. + +#. The best way to interact with the edx-platform REST API is by making + requests using the JWT Authorization header. User the ``client_id`` and + ``client_secret`` to get a JWT token. + + .. code-block:: python + + import base64 + import requests + + client_id = "vovj0AItd9EnrOKjkDli0HpSF9HoooaTY9yueafn" + client_secret = "a3Fkwr24dfDSlIXt3v3q4Ob41CYQNZyGmtK8Y8ax0srpIa2vJON3OC5Rvj1i1wizsIUv1W1qM1Q2XPeuyjucNixsHXZsuw1dn2B9nH3IyjSvuFb5KoydDvWX8Hx8znqD" + + credential = f"{client_id}:{client_secret}" + encoded_credential = base64.b64encode(credential.encode("utf-8")).decode("utf-8") + + headers = {"Authorization": f"Basic {encoded_credential}", "Cache-Control": "no-cache"} + data = {"grant_type": "client_credentials", "token_type": "jwt"} + + token_request = requests.post( + "http://localhost:8000/oauth2/access_token", headers=headers, data=data + ) + access_token = token_request.json()["access_token"] + + +#. The code above will produce a JWT token that you can use to hit any existing + edx-platform API endpoint. + + .. code-block:: python + :name: Example, get all courses you're enrolled in. + :caption: Example, get all of UserA's Enrollments + + + enrollment_request = requests.get( + "http://localhost:8000/api/enrollment/v1/enrollment", + headers={"Authorization": f"JWT {access_token}"}, + ) + + +.. seealso:: + + * :doc:`/concepts/rest_apis` diff --git a/docs/references/lms_apis.rst b/docs/references/lms_apis.rst index 7c77b47e5005..3776da77a3d9 100644 --- a/docs/references/lms_apis.rst +++ b/docs/references/lms_apis.rst @@ -3,5 +3,9 @@ LMS APIs The LMS currently has the following API Endpoints. +.. note:: + + Checkout :doc:`/how-tos/use_the_api` to learn how to authenticate against + these APIs .. openapi:: ../lms-openapi.yaml