docs: Add some basic docs on the Rest API.

There is probably a lot more to say but add a quick How-To and concept
docs that we can build on.

docs/concepts/index.rst

@@ -10,3 +10,4 @@ Concepts and Guides
     frontend/styling
     frontend/bootstrap
     frontend/static_assets
+    rest_apis

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 <https://openedx.atlassian.net/wiki/spaces/AC/pages/42599769/OAuth2+JWT+and+Mobile>`_

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`

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