Merge pull request #73 from edx/markhoeber-doc1988

Video data API doc

analytics_data_api/v0/views/courses.py

@@ -680,7 +680,7 @@ GROUP BY module_id;
 
 class VideosListView(BaseCourseView):
     """
-    Get videos for a course.
+    Get data for the videos in a course.
 
     **Example request**
 
@@ -688,14 +688,15 @@ class VideosListView(BaseCourseView):
 
     **Response Values**
 
-        Returns a collection of video views and metadata for each video. Each collection contains:
+        Returns a collection of video views and metadata for each video.
+        For each video, the collection the following data.
 
             * video_id: The ID of the video.
             * encoded_module_id: The encoded module ID.
-            * duration: Length of the video in seconds.
-            * segment_length: Length of each segment of the video in seconds.
-            * start_views: Number of views at the start of the video.
-            * end_views: Number of views at the end of the video.
+            * duration: The length of the video in seconds.
+            * segment_length: The length of each segment of the video in seconds.
+            * start_views: The number of views at the start of the video.
+            * end_views: The number of views at the end of the video.
             * created: The date the video data was updated.
     """
 

analytics_data_api/v0/views/videos.py

@@ -10,19 +10,20 @@ from analytics_data_api.v0.serializers import VideoTimelineSerializer
 
 class VideoTimelineView(generics.ListAPIView):
     """
-    Get the timeline for a video.
+    Get the counts of users and views for a video.
 
-    **Example request**
+    **Example Request**
 
         GET /api/v0/videos/{video_id}/timeline/
 
     **Response Values**
 
-        Returns viewing data for segments of a video.  Each collection contains:
+        Returns viewing data for each segment of a video.  For each segment,
+        the collection contains the following data.
 
-            * segment: Order of the segment in the timeline.
-            * num_users: Number of unique users that have viewed this segment.
-            * num_views: Number of total views for this segment.
+            * segment: The order of the segment in the video timeline.
+            * num_users: The number of unique users who viewed this segment.
+            * num_views: The number of views for this segment.
             * created: The date the segment data was computed.
     """
 

docs/api/source/change_log.rst

+############
+Change Log
+############
+
+.. list-table::
+   :widths: 10 70
+   :header-rows: 1
+
+   * - Date
+     - Change
+   * - 05/18/15
+     - Added :ref:`Get the Course Video Data` and :ref:`Video Data API`.

docs/api/source/conf.py

@@ -45,7 +45,7 @@ extensions = [
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = ['build']
+exclude_patterns = ['build', 'links.rst']
 
 project = u'edX Data Analytics API Version 0 Alpha'
-copyright = u'2014, edX'
+copyright = u'2015, edX'

docs/api/source/courses.rst

-##################################################
-Course Information API Module
-##################################################
+#######################
+Course Information API
+#######################
 
-This page contains information to:
-
-* `Get Weekly Course Activity`_
-* `Get Recent Course Activity`_
-* `Get the Course Enrollment`_
-* `Get the Course Enrollment by Mode`_
-* `Get the Course Enrollment by Birth Year`_
-* `Get the Course Enrollment by Education Level`_
-* `Get the Course Enrollment by Gender`_
-* `Get the Course Enrollment by Location`_
+.. contents:: Section Contents 
+  :local:
+  :depth: 1
   
 .. _Get Weekly Course Activity:
 
@@ -21,7 +14,7 @@ Get Weekly Course Activity
 
 .. autoclass:: analytics_data_api.v0.views.courses.CourseActivityWeeklyView
 
-**Example response**
+**Example Response**
 
 .. code-block:: json
 
@@ -42,7 +35,6 @@ Get Weekly Course Activity
       }
     ]
 
-
 .. _Get Recent Course Activity:
 
 ***************************
@@ -51,7 +43,7 @@ Get Recent Course Activity
 
 .. autoclass:: analytics_data_api.v0.views.courses.CourseActivityMostRecentWeekView
 
-**Example response**
+**Example Response**
 
 .. code-block:: json
 
@@ -76,7 +68,7 @@ Get the Course Enrollment
 
 .. autoclass:: analytics_data_api.v0.views.courses.CourseEnrollmentView
 
-**Example response**
+**Example Response**
 
 .. code-block:: json
 
@@ -101,7 +93,7 @@ Get the Course Enrollment by Mode
 
 .. autoclass:: analytics_data_api.v0.views.courses.CourseEnrollmentModeView
 
-**Example response**
+**Example Response**
 
 .. code-block:: json
 
@@ -130,7 +122,7 @@ Get the Course Enrollment by Birth Year
 
 .. autoclass:: analytics_data_api.v0.views.courses.CourseEnrollmentByBirthYearView
 
-**Example response**
+**Example Response**
 
 .. code-block:: json
 
@@ -164,7 +156,7 @@ Get the Course Enrollment by Education Level
 
 .. autoclass:: analytics_data_api.v0.views.courses.CourseEnrollmentByEducationView
 
-**Example response**
+**Example Response**
 
 .. code-block:: json
 
@@ -198,7 +190,7 @@ Get the Course Enrollment by Gender
 
 .. autoclass:: analytics_data_api.v0.views.courses.CourseEnrollmentByGenderView
 
-**Example response**
+**Example Response**
 
 .. code-block:: json
 
@@ -229,7 +221,7 @@ Get the Course Enrollment by Location
 
 See `ISO 3166 country codes`_ for more information.
 
-**Example response**
+**Example Response**
 
 .. code-block:: json
 
@@ -263,4 +255,46 @@ See `ISO 3166 country codes`_ for more information.
       }
     ]
 
+.. _Get the Course Video Data:
+
+************************************************
+Get the Course Video Data
+************************************************
+
+.. autoclass:: analytics_data_api.v0.views.courses.VideosListView
+
+**Example Response**
+
+.. code-block:: json
+
+    HTTP 200 OK  
+    Vary: Accept   
+    Content-Type: text/html; charset=utf-8   
+    Allow: GET, HEAD, OPTIONS 
+
+    [
+      {
+        "pipeline_video_id": "UniversityX/UX.3.01x/1T2015|i4x-UniversityX-
+          UX_3_01x-video-02874e0ae0c74ae7b16faa5d6fdc8085",
+        "encoded_module_id": "i4x-UX-UT_3_01x-video-
+          02874e0ae0c74ae7b16faa5d6fdc8085",
+        "duration": 142,
+        "segment_length": 5,
+        "start_views": 2,
+        "end_views": 0,
+        "created": "2015-04-15T214158"
+      },
+      {
+        "pipeline_video_id": "UniversityX/UX.3.01x/1T2015|i4x-UniversityX-
+          UX_3_01x-video-03454e0ae0c72ae7b16fab3d6fdc2143",
+        "encoded_module_id": "i4x-UX-UT_3_01x-video-
+          03454e0ae0c72ae7b16fab3d6fdc2143",
+        "duration": 66,
+        "segment_length": 5,
+        "start_views": 1044,
+        "end_views": 0,
+        "created": "2015-04-15T214158"
+      },     
+    ]
+
 .. include:: links.rst

docs/api/source/endpoints.rst

 .. _Data Analytics API:
 
-################################################
+#################################
 edX Data Analytics API Endpoints
-################################################
+#################################
 
 The edX Platform API allows you to view information about users and their course enrollments, course information, and videos and transcripts.
 
@@ -31,10 +31,14 @@ The following tasks and endpoints are currently supported.
      - /api/v0/courses/{course_id}/enrollment/gender/ 
    * - :ref:`Get the Course Enrollment by Location`
      - /api/v0/courses/{course_id}/enrollment/location/
+   * - :ref:`Get the Course Video Data`
+     - /api/v0/courses/{course_id}/videos/
    * - :ref:`Get the Grade Distribution for a Course`
      - /api/v0/problems/{problem_id}/grade_distribution
    * - :ref:`Get the Answer Distribution for a Problem`
      - /api/v0/problems/{problem_id}/answer_distribution
    * - :ref:`Get the View Count for a Subsection`
      - /api/v0/problems/{module_id}/sequential_open_distribution
+   * - :ref:`Get the Timeline for a Video`
+     - /api/v0/videos/{video_id}/timeline/
    
\ No newline at end of file

docs/api/source/index.rst

@@ -6,9 +6,11 @@ edX Data Analytics API Version 0
     :maxdepth: 2
     
     read_me
+    change_log
     overview
     setup
     authentication
     endpoints
     courses
     problems
+    videos

docs/api/source/overview.rst

 .. _edX Data Analytics API Overview:
 
-################################################
+################################
 edX Data Analytics API Overview
-################################################
+################################
 
 The edX Data Analytics API provides the tools for building applications to view
 and analyze student activity in your course.
 
-The edX Data Analytics API uses Representational State Transfer (REST) design
-principles and supports JavaScript Object Notation (JSON) data-interchange
-format. Our REST API is simple, lightweight and optimized.
-
-You can use the edX Data Analytics API for web, desktop, and mobile
-applications.
+The edX Platform APIs use REST design principles and support the JSON 
+data-interchange format.
 
 ****************************************
 edX Data Analytics API Version 0, Alpha
@@ -44,6 +40,8 @@ With the edX Data Analytics API, you can:
 * :ref:`Get the Course Enrollment by Education Level`
 * :ref:`Get the Course Enrollment by Gender`
 * :ref:`Get the Course Enrollment by Location`
+* :ref:`Get the Course Video Data`
 * :ref:`Get the Grade Distribution for a Course`
 * :ref:`Get the Answer Distribution for a Problem`
 * :ref:`Get the View Count for a Subsection`
+* :ref:`Get the Timeline for a Video`

docs/api/source/problems.rst

-##################################################
-Problem Information API Module
-##################################################
+########################
+Problem Information API
+########################
 
-This page contains information to:
+.. contents:: Section Contents 
+  :local:
+  :depth: 1
   
-* `Get the Grade Distribution for a Course`_
-* `Get the Answer Distribution for a Problem`_
-* `Get the View Count for a Subsection`_
-  
- .. _Get the Grade Distribution for a Course:
+.. _Get the Grade Distribution for a Course:
 
 ***************************************
 Get the Grade Distribution for a Course
@@ -16,7 +14,7 @@ Get the Grade Distribution for a Course
 
 .. autoclass:: analytics_data_api.v0.views.problems.GradeDistributionView 
 
-**Example response**
+**Example Response**
 
 .. code-block:: json
 
@@ -52,7 +50,7 @@ Get the Answer Distribution for a Problem
 
 .. autoclass:: analytics_data_api.v0.views.problems.ProblemResponseAnswerDistributionView
 
-**Example response**
+**Example Response**
 
 .. code-block:: json
 
@@ -106,7 +104,7 @@ Get the View Count for a Subsection
 
 .. autoclass:: analytics_data_api.v0.views.problems.SequentialOpenDistributionView
 
-**Example response**
+**Example Response**
 
 .. code-block:: json
 

docs/api/source/videos.rst

+.. _Video Data API:
+
+###############
+Video Data API
+###############
+
+.. contents:: Section Contents 
+  :local:
+  :depth: 1
+
+.. _Get the Timeline for a Video:
+
+***************************************
+Get the Timeline for a Video
+***************************************
+
+.. autoclass:: analytics_data_api.v0.views.videos.VideoTimelineView 
+
+**Example Response**
+
+.. code-block:: json
+
+    HTTP 200 OK  
+    Vary: Accept   
+    Content-Type: text/html; charset=utf-8   
+    Allow: GET, HEAD, OPTIONS 
+
+    [
+      {
+        "segment": 0,
+        "num_users": 472,
+        "num_views": 539,
+        "created": "2015-05-13T050419"
+      },
+      {
+        "segment": 1,
+        "num_users": 450,
+        "num_views": 510,
+        "created": "2015-05-13T050419"
+      },
+      {
+        "segment": 2,
+        "num_users": 438,
+        "num_views": 493,
+        "created": "2015-05-13T050419"
+      }
+    ]