Andal.LND/edx-platform
6
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

Merge pull request #5491 from edx/markhoeber-doc989

Browse Source 
WIP: edX Mobile API Doc
This commit is contained in:
Mark Hoeber
2014-10-20 09:26:27 -04:00
parent 6bb878afb2 0ea2254062
commit 5ee7f4eba5
20 changed files with 1173 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files

164
docs/en_us/platform_api/Makefile Normal file
View File

@@ -0,0 +1,164 @@
# Makefile for Sphinx documentation
#
# You can set these variables from the command line.
SPHINXOPTS ?=
SPHINXBUILD ?= sphinx-build
PAPER ?=
BUILDDIR ?= build
# User-friendly check for sphinx-build
ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
endif
Q_FLAG =
ifeq ($(quiet), true)
Q_FLAG = -Q
endif
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS = $(Q_FLAG) -d $(BUILDDIR)/doctrees -c source $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
# the i18n builder cannot share the environment and doctrees with the others
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
help:
@echo "Please use \`make <target>' where <target> is one of"
@echo " html to make standalone HTML files"
@echo " dirhtml to make HTML files named index.html in directories"
@echo " singlehtml to make a single large HTML file"
@echo " pickle to make pickle files"
@echo " json to make JSON files"
@echo " htmlhelp to make HTML files and a HTML help project"
@echo " qthelp to make HTML files and a qthelp project"
@echo " devhelp to make HTML files and a Devhelp project"
@echo " epub to make an epub"
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
@echo " latexpdf to make LaTeX files and run them through pdflatex"
@echo " text to make text files"
@echo " man to make manual pages"
@echo " texinfo to make Texinfo files"
@echo " info to make Texinfo files and run them through makeinfo"
@echo " gettext to make PO message catalogs"
@echo " changes to make an overview of all changed/added/deprecated items"
@echo " linkcheck to check all external links for integrity"
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
clean:
-rm -rf $(BUILDDIR)/*
html:
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
dirhtml:
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
singlehtml:
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
@echo
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
pickle:
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
@echo
@echo "Build finished; now you can process the pickle files."
json:
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
@echo
@echo "Build finished; now you can process the JSON files."
htmlhelp:
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
@echo
@echo "Build finished; now you can run HTML Help Workshop with the" \
".hhp project file in $(BUILDDIR)/htmlhelp."
qthelp:
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
@echo
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/edX.qhcp"
@echo "To view the help file:"
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/edX.qhc"
devhelp:
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
@echo
@echo "Build finished."
@echo "To view the help file:"
@echo "# mkdir -p $$HOME/.local/share/devhelp/edX"
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/edX"
@echo "# devhelp"
epub:
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
@echo
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
latex:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
@echo "Run \`make' in that directory to run these through (pdf)latex" \
"(use \`make latexpdf' here to do that automatically)."
latexpdf:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through pdflatex..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
text:
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
@echo
@echo "Build finished. The text files are in $(BUILDDIR)/text."
man:
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
@echo
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
texinfo:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo
@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
@echo "Run \`make' in that directory to run these through makeinfo" \
"(use \`make info' here to do that automatically)."
info:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo "Running Texinfo files through makeinfo..."
make -C $(BUILDDIR)/texinfo info
@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
gettext:
$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
@echo
@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
changes:
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
@echo
@echo "The overview file is in $(BUILDDIR)/changes."
linkcheck:
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
@echo
@echo "Link check complete; look for any errors in the above output " \
"or in $(BUILDDIR)/linkcheck/output.txt."
doctest:
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
@echo "Testing of doctests in the sources finished, look at the " \
"results in $(BUILDDIR)/doctest/output.txt."

0
docs/en_us/platform_api/__init__.py Normal file
View File

9
docs/en_us/platform_api/requirements.txt Normal file
View File

@@ -0,0 +1,9 @@
path.py
Django >=1.4,<1.5
pytz
-e git+https://github.com/edx/XBlock.git#egg=XBlock
lxml
sphinxcontrib-napoleon==0.2.6
stevedore==0.14.1
djangorestframework==2.3.14
PyYAML>=3.10

0
docs/en_us/platform_api/source/__init__.py Normal file
View File

BIN
docs/en_us/platform_api/source/_static/homepage-bg.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 157 KiB

5
docs/en_us/platform_api/source/_templates/layout.html Normal file
View File

@@ -0,0 +1,5 @@
{% extends "!layout.html" %}
{% block header %}
<img src="{{ pathto("_static/homepage-bg.jpg", 1) }}" alt="Edx logo" width="100%;"/>
{% endblock %}

23
docs/en_us/platform_api/source/authentication.rst Normal file
View File

@@ -0,0 +1,23 @@
.. _edX API Authentication:
#############################
edX API Authentication
#############################
*************
OAuth 2.0
*************
The edX Platform API uses OAuth 2.0 for authentication. OAuth 2.0 is an open
standard used by many systems that require secure user authentication. See the
`OAuth 2.0 Standard`_ standard for more information.
***************************************
Registering with Your Open edX Instance
***************************************
To use the edX Platform API with courses on you instance of Open edX, you must register your application with the Open edX server. See the OAuth 2.0 specification for details.
.. include:: links.rst

222
docs/en_us/platform_api/source/conf.py Normal file
View File

@@ -0,0 +1,222 @@
# -*- coding: utf-8 -*-
# pylint: disable=C0103
# pylint: disable=W0622
# pylint: disable=W0212
# pylint: disable=W0613
import sys, os
from path import path
on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
sys.path.append('../../../../')
from docs.shared.conf import *
# Add any paths that contain templates here, relative to this directory.
#templates_path.append('source/_templates')
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
#html_static_path.append('source/_static')
if not on_rtd: # only import and set the theme if we're building docs locally
import sphinx_rtd_theme
html_theme = 'sphinx_rtd_theme'
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
root = path('../../../..').abspath()
sys.path.insert(0, root)
sys.path.append(root / "lms/djangoapps/mobile_api")
sys.path.append(root / "lms/djangoapps/mobile_api/course_info")
sys.path.append(root / "lms/djangoapps/mobile_api/users")
sys.path.append(root / "lms/djangoapps/mobile_api/video_outlines")
sys.path.insert(0, os.path.abspath(os.path.normpath(os.path.dirname(__file__)
+ '/../../../')))
sys.path.append('.')
# django configuration - careful here
if on_rtd:
os.environ['DJANGO_SETTINGS_MODULE'] = 'lms'
else:
os.environ['DJANGO_SETTINGS_MODULE'] = 'lms.envs.test'
# -- General configuration -----------------------------------------------------
# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = [
'sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.intersphinx',
'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.pngmath',
'sphinx.ext.mathjax', 'sphinx.ext.viewcode', 'sphinxcontrib.napoleon']
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = ['build']
# Output file base name for HTML help builder.
htmlhelp_basename = 'edXDocs'
project = u'edX Platform API Version 0.5 Alpha'
copyright = u'2014, edX'
# --- Mock modules ------------------------------------------------------------
# Mock all the modules that the readthedocs build can't import
class Mock(object):
def __init__(self, *args, **kwargs):
pass
def __call__(self, *args, **kwargs):
return Mock()
@classmethod
def __getattr__(cls, name):
if name in ('__file__', '__path__'):
return '/dev/null'
elif name[0] == name[0].upper():
mockType = type(name, (), {})
mockType.__module__ = __name__
return mockType
else:
return Mock()
# The list of modules and submodules that we know give RTD trouble.
# Make sure you've tried including the relevant package in
# docs/share/requirements.txt before adding to this list.
MOCK_MODULES = [
'bson',
'bson.errors',
'bson.objectid',
'dateutil',
'dateutil.parser',
'fs',
'fs.errors',
'fs.osfs',
'lazy',
'mako',
'mako.template',
'matplotlib',
'matplotlib.pyplot',
'mock',
'numpy',
'oauthlib',
'oauthlib.oauth1',
'oauthlib.oauth1.rfc5849',
'PIL',
'pymongo',
'pyparsing',
'pysrt',
'requests',
'scipy.interpolate',
'scipy.constants',
'scipy.optimize',
'yaml',
'webob',
'webob.multidict',
]
if on_rtd:
for mod_name in MOCK_MODULES:
sys.modules[mod_name] = Mock()
# -----------------------------------------------------------------------------
# from http://djangosnippets.org/snippets/2533/
# autogenerate models definitions
import inspect
import types
from HTMLParser import HTMLParser
def force_unicode(s, encoding='utf-8', strings_only=False, errors='strict'):
"""
Similar to smart_unicode, except that lazy instances are resolved to
strings, rather than kept as lazy objects.
If strings_only is True, don't convert (some) non-string-like objects.
"""
if strings_only and isinstance(s, (types.NoneType, int)):
return s
if not isinstance(s, basestring,):
if hasattr(s, '__unicode__'):
s = unicode(s)
else:
s = unicode(str(s), encoding, errors)
elif not isinstance(s, unicode):
s = unicode(s, encoding, errors)
return s
class MLStripper(HTMLParser):
def __init__(self):
self.reset()
self.fed = []
def handle_data(self, d):
self.fed.append(d)
def get_data(self):
return ''.join(self.fed)
def strip_tags(html):
s = MLStripper()
s.feed(html)
return s.get_data()
def process_docstring(app, what, name, obj, options, lines):
"""Autodoc django models"""
# This causes import errors if left outside the function
from django.db import models
# If you want extract docs from django forms:
# from django import forms
# from django.forms.models import BaseInlineFormSet
# Only look at objects that inherit from Django's base MODEL class
if inspect.isclass(obj) and issubclass(obj, models.Model):
# Grab the field list from the meta class
fields = obj._meta._fields()
for field in fields:
# Decode and strip any html out of the field's help text
help_text = strip_tags(force_unicode(field.help_text))
# Decode and capitalize the verbose name, for use if there isn't
# any help text
verbose_name = force_unicode(field.verbose_name).capitalize()
if help_text:
# Add the model field to the end of the docstring as a param
# using the help text as the description
lines.append(u':param %s: %s' % (field.attname, help_text))
else:
# Add the model field to the end of the docstring as a param
# using the verbose name as the description
lines.append(u':param %s: %s' % (field.attname, verbose_name))
# Add the field's type to the docstring
lines.append(u':type %s: %s' % (field.attname, type(field).__name__))
return lines
def setup(app):
"""Setup docsting processors"""
#Register the docstring processor with sphinx
app.connect('autodoc-process-docstring', process_docstring)

173
docs/en_us/platform_api/source/course_info.rst Normal file
View File

@@ -0,0 +1,173 @@
##################################################
Course Information API Module
##################################################
.. module:: mobile_api
This page contains docstrings and example responses for:
* `Get Course Updates`_
* `Get Course Handouts`_
* `Get the Course About Page`_
.. _Get Course Updates:
*******************
Get Course Updates
*******************
.. .. autoclass:: course_info.views.CourseUpdatesList
**Use Case**
Get the content for course updates.
**Example request**:
``GET /api/mobile/v0.5/course_info/{organization}/{course_number}/{course_run}/updates``
**Response Values**
A array of course updates. Each course update contains:
* date: The date of the course update.
* content: The content, as a string, of the course update. HTML tags are not
included in the string.
* status: Whether the update is visible or not.
* id: The unique identifier of the update.
**Example response**
.. code-block:: json
HTTP 200 OK
Content-Type: application/json
Vary: Accept
Allow: GET, HEAD, OPTIONS
[
{
"date": "October 4, 2014",
"content": "Reminder about the quiz due today.
"status": "visible",
"id": 2
},
{ "date": "October 1, 2014",
"content": "Welcome to the course. We
built this to help you become more familiar with taking a course on
edX prior to your first day of class. \n<br>\n<br>\nIn a live course,
this section is where all of the latest course announcements and
updates would be.,
"id": 1 } ]
.. _Get Course Handouts:
*******************
Get Course Handouts
*******************
.. .. autoclass:: course_info.views.CourseHandoutsList
**Use Case**
Get the HTML for course handouts.
**Example request**:
``GET /api/mobile/v0.5/course_info/{organization}/{course_number}/{course_run}/handouts``
**Response Values**
* handouts_html: The HTML for course handouts.
**Example response**
.. code-block:: json
HTTP 200 OK
Content-Type: application/json
Vary: Accept
Allow: GET, HEAD, OPTIONS
{
"handouts_html": "\n\n<ol class=\"treeview-handoutsnav\">\n
<li><a href=\"/static/demoPDF.pdf\">Example handout</a></li>
</ol>\n\n"
}
.. _Get the Course About Page:
**************************
Get the Course About Page
**************************
.. .. autoclass:: course_info.views.CourseAboutDetail
.. :members:
**Use Case**
Get the HTML for the course about page.
**Example request**:
``GET /api/mobile/v0.5/course_info/{organization}/{course_number}/{course_run}/about``
**Response Values**
* overview: The HTML for the course About page.
**Example response**
.. code-block:: json
HTTP 200 OK
Content-Type: application/json
Vary: Accept
Allow: GET, HEAD, OPTIONS
{
"overview": "<section class=\"about\">\n
<h2>About This Course</h2>\n
<p>Include your long course description here. The long course description should contain 150-400 words.</p>
<p>This is paragraph 2 of the long course description. Add more paragraphs as needed. Make sure to enclose them in paragraph tags.</p>
</section>\n\n
<section class=\"prerequisites\">\n
<h2>Prerequisites</h2>\n
<p>Add information about course prerequisites here.</p>\n </section>\n\n
<section class=\"course-staff\">\n
<h2>Course Staff</h2>\n
<article class=\"teacher\">\n
<div class=\"teacher-image\">\n
<img src=\"/static/images/pl-faculty.png\" align=\"left\" style=\"margin:0 20 px 0\">\n
</div>\n\n
<h3>Staff Member #1</h3>\n
<p>Biography of instructor/staff member #1</p>\n
</article>\n\n
<article class=\"teacher\">\n
<div class=\"teacher-image\">\n
<img src=\"/static/images/pl-faculty.png\" align=\"left\" style=\"margin:0 20 px 0\">\n
</div>\n\n
<h3>Staff Member #2</h3>\n
<p>Biography of instructor/staff member #2</p>\n
</article>\n
</section>\n\n
<section class=\"faq\">\n
<section class=\"responses\">\n
<h2>Frequently Asked Questions</h2>\n
<article class=\"response\">\n
<h3>Do I need to buy a textbook?</h3>\n
<p>No, a free online version of Chemistry: Principles, Patterns, and Applications, First Edition by Bruce Averill and Patricia Eldredge will be available, though you can purchase a printed version (published by FlatWorld Knowledge) if you\u2019d like.</p>\n
</article>\n\n
<article class=\"response\">\n
<h3>Question #2</h3>\n
<p>Your answer would be displayed here.</p>\n
</article>\n
</section>\n
</section>"
}

31
docs/en_us/platform_api/source/endpoints.rst Normal file
View File

@@ -0,0 +1,31 @@
.. _edX Platform API Endpoints:
################################################
edX LMS Platform Endpoints
################################################
The edX Platform API allows you to view information about users and their course enrollments, course information, and videos and transcripts.
The following tasks and endpoints are currently supported.
.. list-table::
:widths: 10 70
:header-rows: 1
* - To:
- Use this endpoint:
* - :ref:`Get details about a user<Get User Details>`
- /api/mobile/v0.5/users/{username}
* - :ref:`Get course enrollments for about a user<Get a User's Course Enrollments>`
- /api/mobile/v0.5/users/{username}/course_enrollments/
* - :ref:`Get a course About page<Get the Course About Page>`
- /api/mobile/v0.5/course_info/{organization}/{course_number}/{course_run}/about
* - :ref:`Get updates for a course<Get Course Updates>`
- /api/mobile/v0.5/course_info/{organization}/{course_number}/{course_run}/updates
* - :ref:`Get handouts for a course<Get Course Handouts>`
- /api/mobile/v0.5/course_info/{organization}/{course_number}/{course_run}/handouts
* - :ref:`Get videos in a course<Get the Video List>`
- /api/mobile/v0.5/video_outlines/courses/{organization}/{course_number}/{course_run}
* - :ref:`Get a video transcript<Get a Video Transcript>`
- /api/mobile/v0.5/video_outlines/transcripts/{organization}/{course_number}/{course_run}/{video ID}/{language code}

15
docs/en_us/platform_api/source/index.rst Normal file
View File

@@ -0,0 +1,15 @@
################################################
edX Platform API Version 0.5
################################################
.. toctree::
:maxdepth: 2
read_me
preface
overview
authentication
endpoints
users
course_info
video_outlines

1
docs/en_us/platform_api/source/links.rst Normal file
View File

@@ -0,0 +1 @@
.. _OAuth 2.0 Standard: https://tools.ietf.org/html/draft-ietf-oauth-v2-31

43
docs/en_us/platform_api/source/overview.rst Normal file
View File

@@ -0,0 +1,43 @@
.. _edX Platform API Overview:
################################################
edX Platform API Overview
################################################
The edX Platform API enables you to build applications for students to view
course information and videos for courses on your instance of Open edX.
The edX Platform 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 Platform API for web, desktop, and mobile applications.
*************************************
edX Platform API Version 0.5, Alpha
*************************************
The edX Platform API is currently at version 0.5 and is an Alpha release. We
plan on making significant enhancements and changes to the API.
.. caution::
As this is a new and rapidly evolving API, at this time edX does not guarantee
forward compatibility. We encourage you to use and experiment with the API,
while keeping in mind that endpoints may change.
******************************
edX Platform API Capabilities
******************************
With the edX Platform API, you can:
* Get :ref:`user details<Get User Details>` and :ref:`course enrollments<Get a
User's Course Enrollments>` for a user.
* Get :ref:`course information<Get the Course About Page>`, :ref:`updates<Get
Course Updates>`, and :ref:`handouts<Get Course Handouts>` for courses the
user is enrolled in.
* Get :ref:`videos<Get the Video List>` and :ref:`transcripts<Get a Video
Transcript>` for courses the user is enrolled in.

1
docs/en_us/platform_api/source/preface.rst Normal file
View File

@@ -0,0 +1 @@
.. include:: ../../shared/preface.rst

17
docs/en_us/platform_api/source/read_me.rst Normal file
View File

@@ -0,0 +1,17 @@
########
Read Me
########
The edX Platform API documentation is created using RST_
files and Sphinx_. You, the user community, can help update and revise this
documentation project on GitHub:
https://github.com/edx/edx-platform/tree/master/docs/platforms_api/source
To suggest a revision, fork the project, make changes in your fork, and submit
a pull request back to the original project: this is known as the `GitHub Flow`_.
.. _Sphinx: http://sphinx-doc.org/
.. _LaTeX: http://www.latex-project.org/
.. _`GitHub Flow`: https://github.com/blog/1557-github-flow-in-the-browser
.. _RST: http://docutils.sourceforge.net/rst.html

168
docs/en_us/platform_api/source/users.rst Normal file
View File

@@ -0,0 +1,168 @@
#########################
User API Module
#########################
.. module:: mobile_api
This page describes how to use the mobile user API to:
* `Get User Details`_
* `Get a User's Course Enrollments`_
.. _Get User Details:
*******************
Get User Details
*******************
.. .. autoclass:: mobile_api.users.views.UserDetail
.. :members:
**Use Case**
Get information about the specified user and access other resources the user
has permissions for.
Users are redirected to this endpoint after logging in.
You can use the **course_enrollments** value in the response to get a list of
courses the user is enrolled in.
**Example request**:
``GET /api/mobile/v0.5/users/{username}``
**Response Values**
* id: The ID of the user.
* username: The username of the currently logged in user.
* email: The email address of the currently logged in user.
* name: The full name of the currently logged in user.
* course_enrollments: The URI to list the courses the currently logged in user
is enrolled in.
**Example response**
.. code-block:: json
HTTP 200 OK
Vary: Accept
Content-Type: text/html; charset=utf-8
Allow: GET, HEAD, OPTIONS
{
"id": 67,
"username": "mtwain",
"email": "mtwain@email-domain.com",
"name": "mtwain",
"course_enrollments": "http://localhost:8000/api/mobile/v0.5/users/mtwain/course_enrollments/"
}
.. _Get a User's Course Enrollments:
**************************************
Get a User's Course Enrollments
**************************************
.. .. autoclass:: users.views.UserCourseEnrollmentsList
.. :members:
**Use Case**
Get information about the courses the currently logged in user is enrolled in.
**Example request**:
``GET /api/mobile/v0.5/users/{username}/course_enrollments/``
**Response Values**
* created: The date the course was created.
* mode: The type of certificate registration for this course: honor or
certified.
* is_active: Whether the course is currently active; true or false.
* course: A collection of data about the course:
* course_about: The URI to get the data for the course About page.
* course_updates: The URI to get data for course updates.
* number: The course number.
* org: The organization that created the course.
* video_outline: The URI to get the list of all vides the user can access in
the course.
* id: The unique ID of the course.
* latest_updates: Reserved for future use.
* end: The end date of the course.
* name: The name of the course.
* course_handouts: The URI to get data for course handouts.
* start: The data and time the course starts.
* course_image: The path to the course image.
**Example response**
.. code-block:: json
HTTP 200 OK
Vary: Accept
Content-Type: text/html; charset=utf-8
Allow: GET, HEAD, OPTIONS
{
"created": "2014-04-18T13:44:25Z",
"mode": "honor",
"is_active": true,
"course": {
"course_about": "http://localhost:8000/api/mobile/v0.5/course_info/edX/Open_DemoX/edx_demo_course/about",
"course_updates": "http://localhost:8000/api/mobile/v0.5/course_info/edX/Open_DemoX/edx_demo_course/updates",
"number": "Open_DemoX",
"org": "edX",
"video_outline": "http://localhost:8000/api/mobile/v0.5/video_outlines/courses/edX/Open_DemoX/edx_demo_course",
"id": "edX/Open_DemoX/edx_demo_course",
"latest_updates": {
"video": null
},
"end": null,
"name": "edX Demonstration Course",
"course_handouts": "http://localhost:8000/api/mobile/v0.5/course_info/edX/Open_DemoX/edx_demo_course/handouts",
"start": "1970-01-01T05:00:00Z",
"course_image": "/c4x/edX/Open_DemoX/asset/images_course_image.jpg"
}
},
{
"created": "2014-09-29T13:46:06Z",
"mode": "honor",
"is_active": true,
"course": {
"course_about": "http://localhost:8000/api/mobile/v0.5/course_info/edX/DemoX/Demo_Course/about",
"course_updates": "http://localhost:8000/api/mobile/v0.5/course_info/edX/DemoX/Demo_Course/updates",
"number": "DemoX",
"org": "edX",
"video_outline": "http://localhost:8000/api/mobile/v0.5/video_outlines/courses/edX/DemoX/Demo_Course",
"id": "edX/DemoX/Demo_Course",
"latest_updates": {
"video": null
},
"end": null,
"name": "edX Demonstration Course",
"course_handouts": "http://localhost:8000/api/mobile/v0.5/course_info/edX/DemoX/Demo_Course/handouts",
"start": "2013-02-05T05:00:00Z",
"course_image": "/c4x/edX/DemoX/asset/images_course_image.jpg"
}
}

136
docs/en_us/platform_api/source/video_outlines.rst Normal file
View File

@@ -0,0 +1,136 @@
##################################################
Video Outlines API Module
##################################################
.. module:: mobile_api
This page contains docstrings and example responses for:
* `Get the Video List`_
* `Get a Video Transcript`_
.. _Get the Video List:
*******************
Get the Video List
*******************
.. .. autoclass:: video_outlines.views.VideoSummaryList
.. :members:
**Use Case**
Get a list of all videos in the specified course. You can use the video_url
value to access the video file.
**Example request**:
``GET /api/mobile/v0.5/video_outlines/courses/{organization}/{course_number}/{course_run}``
**Response Values**
An array of videos in the course. For each video:
* section_url: The URL to the first page of the section that contains the video
in the Learning Managent System.
* path: An array containing category and name values specifying the complete
path the the video in the courseware hierarcy. The following categories
values are included: "chapter", "sequential", and "vertical". The name value
is the display name for that object.
* unit_url: The URL to the unit contains the video in the Learning Managent
System.
* named_path: An array consisting of the display names of the courseware
objects in the path to the video.
* summary: An array of data about the video that includes:
* category: The type of component, in this case always "video".
* video_thumbnail_url: The URL to the thumbnail image for the video, if
available.
* language: The language code for the video.
* name: The display name of the video.
* video_url: The URL to the video file. Use this value to access the video.
* duration: The length of the video, if available.
* transcripts: An array of language codes and URLs to available video
transcripts. Use the URL value to access a transcript for the video.
* id: The unique identifier for the video.
* size: The size of the video file
**Example response**
.. code-block:: json
HTTP 200 OK
Vary: Accept
Content-Type: text/html; charset=utf-8
Allow: GET, HEAD, OPTIONS
[
{
"section_url": "http://localhost:8000/courses/edX/Open_DemoX/edx_demo_course/courseware/d8a6192ade314473a78242dfeedfbf5b/edx_introduction/",
"path": [
{
"category": "chapter",
"name": "Introduction"
},
{
"category": "sequential",
"name": "Demo Course Overview"
},
{
"category": "vertical",
"name": "Introduction: Video and Sequences"
}
],
"unit_url": "http://localhost:8000/courses/edX/Open_DemoX/edx_demo_course/courseware/d8a6192ade314473a78242dfeedfbf5b/edx_introduction/1",
"named_path": [
"Introduction",
"Demo Course Overview"
],
"summary": {
"category": "video",
"video_thumbnail_url": null,
"language": "en",
"name": "Welcome!",
"video_url": "https://s3.amazonaws.com/edx-course-videos/edx-edx101/EDXSPCPJSP13-H010000_100.mp4",
"duration": null,
"transcripts": {
"en": "http://localhost:8000/api/mobile/v0.5/video_outlines/transcripts/edX/Open_DemoX/edx_demo_course/0b9e39477cf34507a7a48f74be381fdd/en"
},
"id": "i4x://edX/Open_DemoX/video/0b9e39477cf34507a7a48f74be381fdd",
"size": 0
}
}
]
.. _Get a Video Transcript:
***********************
Get a Video Transcript
***********************
.. .. autoclass:: video_outlines.views.VideoTranscripts
.. :members:
**Use Case**
Use to get a transcript for a specified video and language.
**Example request**:
``/api/mobile/v0.5/video_outlines/transcripts/{organization}/{course_number}/{course_run}/{video ID}/{language code}``
**Response Values**
An HttpResponse with an SRT file download.

48
lms/djangoapps/mobile_api/course_info/views.py
View File

@@ -13,10 +13,27 @@ from xmodule.modulestore.django import modulestore
class CourseUpdatesList(generics.ListAPIView):
"""Notes:
"""
**Use Case**
1. This only works for new-style course updates and is not the older freeform
format.
Get the content for course updates.
**Example request**:
GET /api/mobile/v0.5/course_info/{organization}/{course_number}/{course_run}/updates
**Response Values**
A array of course updates. Each course update contains:
* date: The date of the course update.
* content: The content, as a string, of the course update. HTML tags
are not included in the string.
* status: Whether the update is visible or not.
* id: The unique identifier of the update.
"""
authentication_classes = (OAuth2Authentication, SessionAuthentication)
permission_classes = (permissions.IsAuthenticated,)
@@ -33,7 +50,18 @@ class CourseUpdatesList(generics.ListAPIView):
class CourseHandoutsList(generics.ListAPIView):
"""Please just render this in an HTML view for now.
"""
**Use Case**
Get the HTML for course handouts.
**Example request**:
GET /api/mobile/v0.5/course_info/{organization}/{course_number}/{course_run}/handouts
**Response Values**
* handouts_html: The HTML for course handouts.
"""
authentication_classes = (OAuth2Authentication, SessionAuthentication)
permission_classes = (permissions.IsAuthenticated,)
@@ -52,7 +80,17 @@ class CourseHandoutsList(generics.ListAPIView):
class CourseAboutDetail(generics.RetrieveAPIView):
"""
Renders course 'about' page
**Use Case**
Get the HTML for the course about page.
**Example request**:
GET /api/mobile/v0.5/course_info/{organization}/{course_number}/{course_run}/about
**Response Values**
* overview: The HTML for the course About page.
"""
authentication_classes = (OAuth2Authentication, SessionAuthentication)
permission_classes = (permissions.IsAuthenticated,)

62
lms/djangoapps/mobile_api/users/views.py
View File

@@ -23,10 +23,33 @@ class IsUser(permissions.BasePermission):
class UserDetail(generics.RetrieveAPIView):
"""Read-only information about our User.
"""
**Use Case**
This will be where users are redirected to after API login and will serve
as a place to list all useful resources this user can access.
Get information about the specified user and
access other resources the user has permissions for.
Users are redirected to this endpoint after logging in.
You can use the **course_enrollments** value in
the response to get a list of courses the user is enrolled in.
**Example request**:
GET /api/mobile/v0.5/users/{username}
**Response Values**
* id: The ID of the user.
* username: The username of the currently logged in user.
* email: The email address of the currently logged in user.
* name: The full name of the currently logged in user.
* course_enrollments: The URI to list the courses the currently logged
in user is enrolled in.
"""
authentication_classes = (OAuth2Authentication, SessionAuthentication)
permission_classes = (permissions.IsAuthenticated, IsUser)
@@ -39,7 +62,38 @@ class UserDetail(generics.RetrieveAPIView):
class UserCourseEnrollmentsList(generics.ListAPIView):
"""Read-only list of courses that this user is enrolled in."""
"""
**Use Case**
Get information about the courses the currently logged in user is
enrolled in.
**Example request**:
GET /api/mobile/v0.5/users/{username}/course_enrollments/
**Response Values**
* created: The date the course was created.
* mode: The type of certificate registration for this course: honor or
certified.
* is_active: Whether the course is currently active; true or false.
* course: A collection of data about the course:
* course_about: The URI to get the data for the course About page.
* course_updates: The URI to get data for course updates.
* number: The course number.
* org: The organization that created the course.
* video_outline: The URI to get the list of all vides the user can
access in the course.
* id: The unique ID of the course.
* latest_updates: Reserved for future use.
* end: The end date of the course.
* name: The name of the course.
* course_handouts: The URI to get data for course handouts.
* start: The data and time the course starts.
* course_image: The path to the course image.
"""
authentication_classes = (OAuth2Authentication, SessionAuthentication)
permission_classes = (permissions.IsAuthenticated, IsUser)
queryset = CourseEnrollment.objects.all()

67
lms/djangoapps/mobile_api/video_outlines/views.py
View File

@@ -25,7 +25,58 @@ from .serializers import BlockOutline, video_summary
class VideoSummaryList(generics.ListAPIView):
"""A list of all Videos in this Course that the user has access to."""
"""
**Use Case**
Get a list of all videos in the specified course. You can use the
video_url value to access the video file.
**Example request**:
GET /api/mobile/v0.5/video_outlines/courses/{organization}/{course_number}/{course_run}
**Response Values**
An array of videos in the course. For each video:
* section_url: The URL to the first page of the section that
contains the video in the Learning Managent System.
* path: An array containing category and name values specifying the
complete path the the video in the courseware hierarcy. The
following categories values are included: "chapter", "sequential",
and "vertical". The name value is the display name for that object.
* unit_url: The URL to the unit contains the video in the Learning
Managent System.
* named_path: An array consisting of the display names of the
courseware objects in the path to the video.
* summary: An array of data about the video that includes:
* category: The type of component, in this case always "video".
* video_thumbnail_url: The URL to the thumbnail image for the
video, if available.
* language: The language code for the video.
* name: The display name of the video.
* video_url: The URL to the video file. Use this value to access
the video.
* duration: The length of the video, if available.
* transcripts: An array of language codes and URLs to available
video transcripts. Use the URL value to access a transcript
for the video.
* id: The unique identifier for the video.
* size: The size of the video file
"""
authentication_classes = (OAuth2Authentication, SessionAuthentication)
permission_classes = (permissions.IsAuthenticated,)
@@ -45,9 +96,19 @@ class VideoSummaryList(generics.ListAPIView):
class VideoTranscripts(generics.RetrieveAPIView):
"""Read-only view for a single transcript (SRT) file for a particular language.
"""
**Use Case**
Use to get a transcript for a specified video and language.
**Example request**:
GET /api/mobile/v0.5/video_outlines/transcripts/{organization}/{course_number}/{course_run}/{video ID}/{language code}
**Response Values**
An HttpResponse with an SRT file download.
Returns an `HttpResponse` with an SRT file download for the body.
"""
authentication_classes = (OAuth2Authentication, SessionAuthentication)
permission_classes = (permissions.IsAuthenticated,)