Courses and Course Catalog API documentation

docs/en_us/platform_api/source/course_catalog/catalog.rst

-########################################
-Course Catalog API Catalog Resource
-########################################
-
-With the Course Catalog API **Catalog** resource, you can complete the
-following tasks.
-
-.. contents::
-   :local:
-   :depth: 1
-
-
-.. _Get a List of All Catalogs:
-
-***************************
-Get a List of All Catalogs
-***************************
-
-.. class enrollment.views.EnrollmentView(**kwargs)[source] (?)
-
-===============
-Use Case
-===============
-
-Get a list of all catalogs.
-
-===============
-Example Request
-===============
-
-``GET api/v1/catalogs/``
-
-===============
-Response Values
-===============
-
-If the request for information about the user is successful, an HTTP 200 “OK”
-response is returned.
-
-The HTTP 200 response has the following values.
-
-* count
-* next
-* previous
-* results
-
-  * courses_count
-  * id
-  * name
-  * query
-  * viewers
-
-Example response showing a catalog of select courses
-****************************************************
-
-.. code-block:: json
-
-    HTTP 200 OK
-
-    {
-      "Date": "Wed, 20 Apr 2016 19:45:55 GMT",
-      "Content-Encoding": "gzip",
-      "Allow": "GET, POST, HEAD, OPTIONS",
-      "Server": "nginx/1.8.1",
-      "X-Frame-Options": "SAMEORIGIN",
-      "Vary": "Accept-Encoding, Accept, Accept-Language, Cookie",
-      "Content-Language": "en",
-      "Connection": "keep-alive",
-      "Content-Type": "application/json",
-      "Content-Length": "199"
-    }
-
-    {
-      "count": 1,
-      "next": null,
-      "previous": null,
-      "results": [
-        {
-          "id": 1,
-          "name": "All MITx and HarvardX Courses",
-          "query": "{\r\n  \"query\": {\r\n    \"query_string\": {\r\n      \"query\": \"org:(MITx OR HarvardX)\",\r\n      \"analyze_wildcard\": true\r\n    }\r\n  }\r\n}",
-          "courses_count": 0,
-          "viewers": []
-        }
-      ]
-    }
-
-
-
-.. _Create a New Catalog:
-
-***************************
-Create a New Catalog
-***************************
-
-.. class enrollment.views.EnrollmentView(**kwargs)[source] (?)
-
-===============
-Use Case
-===============
-
-Create a new catalog.
-
-===============
-Example Request
-===============
-
-``POST api/v1/catalogs/``
-
-===============
-Parameters
-===============
-
-.. list-table::
-   :widths: 25 25 50
-   :header-rows: 1
-
-   * - Parameter Name
-     - Required
-     - Description
-     - Parameter Type
-     - Data Type
-   * - name
-     - Yes
-     - Catalog name.
-     - form
-     - string
-   * - query
-     - Yes
-     - Query to retrieve catalog contents.
-     - form
-     - string
-   * - viewers
-     - No
-     - Usernames of users with explicit access to view this catalog.
-     - form
-     - string
-
-===============
-Response Values
-===============
-
-If the request for information about the user is successful, an HTTP "201
-CREATED" response is returned.
-
-The HTTP 201 response has the following values.
-
-* courses_count
-* id
-* name
-* query
-* viewers
-
-Example response creating a new catalog
-***************************************
-
-.. code-block:: json
-
-    HTTP 201 CREATED
-
-    {
-      "Date": "Wed, 20 Apr 2016 20:45:09 GMT",
-      "Allow": "GET, POST, HEAD, OPTIONS",
-      "Server": "nginx/1.8.1",
-      "X-Frame-Options": "SAMEORIGIN",
-      "Vary": "Accept, Accept-Language, Cookie",
-      "Content-Language": "en",
-      "Content-Type": "application/json",
-      "Connection": "keep-alive",
-      "Content-Length": "79"
-    }
-
-    {
-      "id": 2,
-      "name": "example_catalog",
-      "query": "example",
-      "courses_count": 6,
-      "viewers": []
-    }
-
-
-
-
-
-.. _Get Details About a Catalog:
-
-***************************
-Get Details About a Catalog
-***************************
-
-.. class enrollment.views.EnrollmentView(**kwargs)[source] (?)
-
-===============
-Use Case
-===============
-
-Get details about a catalog.
-
-===============
-Example Request
-===============
-
-``GET api/v1/catalogs/{id}``
-
-===============
-Parameters
-===============
-
-.. list-table::
-   :widths: 25 25 50
-   :header-rows: 1
-
-   * - Parameter Name
-     - Required
-     - Description
-     - Parameter Type
-     - Data Type
-   * - ``id``
-     - Yes
-     - ******DESCRIPTION NEEDED******
-     - path
-     - string
-
-===============
-Response Values
-===============
-
-If the request for information about the user is successful...

docs/en_us/platform_api/source/course_catalog/index.rst

@@ -7,7 +7,7 @@ Course Catalog API Version 1.0
 .. toctree::
     :maxdepth: 2
 
-    catalog
-    course_runs
-    course
+    catalogs
+    catalogs_id
+    catalogs_id_courses
 

docs/en_us/platform_api/source/course_catalog/overview.rst

+.. _Course Catalog API Overview:
+
+#############################
+Course Catalog API Overview
+#############################
+
+Use the Course Catalog API to obtain information about the catalogs that edX
+offers, as well as information about the courses in a specific catalog.
+
+.. contents::
+   :local:
+   :depth: 1
+
+*****************************************
+Course Catalog API Version and Status
+*****************************************
+
+The Course Catalog API is currently at version 1.0. We plan to make
+significant enhancements to this API.
+
+*****************************
+Course Catalog API Endpoints
+*****************************
+
+The Course Catalog API includes the **Catalogs** resource. This resource
+supports the following tasks, methods, and endpoints.
+
+.. list-table::
+   :widths: 20 10 70
+   :header-rows: 1
+
+   * - Task
+     - Method
+     - Endpoint
+   * - :ref:`Get a list of all available course catalogs <Get a List of All
+     Course Catalogs>`
+     - GET
+     - /api/v1/catalogs/
+   * - :ref:`Get information about a specific catalog <Get Information About a
+     Specific Catalog>`
+     - GET
+     - /api/v1/catalogs/{id}/
+   * - :ref:`Get a list of all courses in a catalog <Get a List of All Courses
+     in a Catalog>`
+     - GET
+     - /api/v1/catalogs/{id}/courses/

docs/en_us/platform_api/source/courses/index.rst

+.. _edX Platform Courses API:
+
+#####################################
+Courses API Version 1.0
+#####################################
+
+.. toctree::
+    :maxdepth: 2
+
+    overview
+    courses
+
+

docs/en_us/platform_api/source/courses/overview.rst

+.. _Courses API Overview:
+
+#############################
+Courses Overview
+#############################
+
+Use the Courses API to obtain information about edX courses.
+
+
+
+.. contents::
+   :local:
+   :depth: 1
+
+*****************************************
+Courses API Version and Status
+*****************************************
+
+The Courses API is currently at version 1.0. We plan to make
+significant enhancements to this API.
+
+*****************************
+Courses API Endpoints
+*****************************
+
+The Courses API includes the **Courses** resource. This resource
+supports the following tasks, methods, and endpoints.
+
+.. list-table::
+   :widths: 20 10 70
+   :header-rows: 1
+
+   * - Task
+     - Method
+     - Endpoint
+   * - :ref:`Get a list of all courses in a catalog <Get a List of All Courses
+     in a Catalog>`
+     - GET
+     - /api/v1/catalogs/{id}/courses/

docs/en_us/platform_api/source/shared/courses_response_values.rst

+.. _Course:
+
+Course
+*******
+
+* count (integer): The number of courses in the catalog.
+* next (string): The URL for the next page of results.
+* previous (string): The URL for the previous page of results.
+* results (array): See :ref:`Results`.
+
+.. _Results:
+
+Results
+*******
+
+Parent: ``course``
+
+A list of courses in the catalog.
+
+* key (string): The unique identifier for the course.
+* title (string): The title of the course.
+* short_description (string): The short description of the course and its
+  content.
+* full_description (string): The long description of the course and its
+  content.
+* level_type (ENUM string): ---DESCRIPTION---
+* subjects (array): Academic subjects that this course covers. See
+  :ref:`Subjects`.
+* prerequisites (array): Any courses a learner must complete before enrolling
+  in the current course. ---This is in strikethrough text in the Google doc. Is
+  it to be deleted?---
+* expected_learning_items (array): ---This is in strikethrough text in the
+  Google doc. Is it to be deleted?---
+* image (array): The About page image for this course. See :ref:`image`.
+* video (array): The course About video. See :ref:`Video`.
+* owners (array): Institution that offers the course. See :ref:`Organization`.
+* sponsors (array): Corporate sponsor for the course. See :ref:`Organization`.
+* modified (datetime): The date and time the course was last modified.
+* course_runs (array): Information about specific runs of the course. See
+  :ref:`Course Runs`.
+* marketing_url: ---DESCRIPTION---
+
+.. _Course Runs:
+
+course_runs
+============
+
+Parent: ``results``
+
+* course
+* key (string): The unique identifier for the course.
+* title (string): The title of the course.
+* short_description (string): The short description of the course and its
+  content.
+* full_description (string): The long description of the course and its
+  content.
+* start (datetime): The course start date.
+* end (datetime): The course end date.
+* enrollment_start (datetime): The course enrollment start date.
+* enrollment_end (datetime): The course enrollment end date.
+* announcement ---Not in Google doc---
+* image (array): See :ref:`Image`.
+* video (array): The About video for this course run. See :ref:`Video`.
+* seats (array): The available modes for this course. See :ref:`Seats`.
+* content_language (string): The language for this course run.
+* transcript_languages (array[string]): Languages in which video transcripts
+  are available. ---This is in strikethrough text in the Google doc. Is
+  it to be deleted?---
+* instructors (array): See :ref:`Person`. ---Not in Google doc---
+* staff (array): Information about the course staff. See :ref:`Person`.
+* pacing_type (ENUM string): The pacing of the course. May be **self-paced** or
+  **instructor-paced**.
+* min_effort (integer): ---Not in Google doc. A different value, "effort", is
+  in strikethrough text. Is this to be deleted? ---
+* max_effort (integer): ---Not in Google doc. A different value, "effort", is
+  in strikethrough text. Is this to be deleted? ---
+* modified (datetime): The date and time the course was last modified.
+
+.. _Image:
+
+image
+======
+
+The following ``image`` objects have identical response values.
+
+* ``image`` (parent: ``course``, ``course_runs``, ``video``)
+* ``logo_image`` (parent: ``organization``)
+* ``profile_image`` (parent: ``person``)
+
+The ``image`` object has the following response values.
+
+* src (string): The URL where the image is located.
+* description (string): A description of the image.
+* height (integer): The height of the image in pixels.
+* width (integer): The width of the image in pixels.
+
+.. _Organization:
+
+organization
+==============
+
+The following ``organization`` objects have identical response values.
+
+* ``owners`` (parent: ``results``)
+* ``sponsors`` (parent: ``results``)
+
+The ``organization`` object has the following response values.
+
+* key (string): The unique ID for the organization.
+* name (string): The name of the organization.
+* description (string): A description of the organization.
+* logo_image (array): See :ref:`Image`.
+* homepage_url (string): The URL of the organization's home page.
+
+.. _Person:
+
+person
+=========
+
+``instructor`` or ``staff``
+
+* key
+* name
+* title
+* bio
+* profile_image (array): See :ref:`Image`.
+
+.. _Prerequisites:
+
+Prerequisites
+==================
+
+Any courses a learner must complete before enrolling in the current course.
+
+* name (string): ---The name of the prerequisite course. (Not course ID? Full name?)---
+
+.. _Seats:
+
+Seats
+=========
+
+* type (string): Audit, verified, professional education
+* price
+* currency
+* upgrade_deadline
+* credit_provider
+* credit_hours
+
+.. _Subjects:
+
+Subjects
+=========
+
+Academic subjects that this course covers.
+
+* name (string): Name of a subject (such as "computer science" or "history".)
+
+**Possible values:**
+
+::
+
+    Architecture
+    Art & Culture
+    Biology & Life Sciences
+    Business & Management
+    Chemistry
+    Communication
+    Computer Science
+    Data Analysis & Statistics
+    Design
+    Economics & Finance
+    Education & Teacher Training
+    Electronics
+    Energy & Earth Sciences
+    Engineering
+    Environmental Studies
+    Ethics
+    Food & Nutrition
+    Health & Safety
+    History
+    Humanities
+    Language
+    Law
+    Literature
+    Math
+    Medicine
+    Music
+    Philanthropy
+    Philosophy & Ethics
+    Physics
+    Science
+    Social Sciences
+
+
+.. _Video:
+
+Video
+=========
+
+``video`` array
+
+* src (string)
+* description (string)
+* image (array): See :ref:`Image`.