diff --git a/docs/en_us/platform_api/Makefile b/docs/en_us/platform_api/Makefile new file mode 100644 index 0000000000..58e5370a97 --- /dev/null +++ b/docs/en_us/platform_api/Makefile @@ -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 ' where 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." diff --git a/docs/en_us/platform_api/__init__.py b/docs/en_us/platform_api/__init__.py new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/en_us/platform_api/requirements.txt b/docs/en_us/platform_api/requirements.txt new file mode 100644 index 0000000000..64a0ffa0e8 --- /dev/null +++ b/docs/en_us/platform_api/requirements.txt @@ -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 diff --git a/docs/en_us/platform_api/source/__init__.py b/docs/en_us/platform_api/source/__init__.py new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/en_us/platform_api/source/_static/homepage-bg.jpg b/docs/en_us/platform_api/source/_static/homepage-bg.jpg new file mode 100644 index 0000000000..61da5545c1 Binary files /dev/null and b/docs/en_us/platform_api/source/_static/homepage-bg.jpg differ diff --git a/docs/en_us/platform_api/source/_templates/layout.html b/docs/en_us/platform_api/source/_templates/layout.html new file mode 100644 index 0000000000..66ff998af1 --- /dev/null +++ b/docs/en_us/platform_api/source/_templates/layout.html @@ -0,0 +1,5 @@ +{% extends "!layout.html" %} + +{% block header %} +Edx logo +{% endblock %} \ No newline at end of file diff --git a/docs/en_us/platform_api/source/authentication.rst b/docs/en_us/platform_api/source/authentication.rst new file mode 100644 index 0000000000..1ee2520fb5 --- /dev/null +++ b/docs/en_us/platform_api/source/authentication.rst @@ -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 \ No newline at end of file diff --git a/docs/en_us/platform_api/source/conf.py b/docs/en_us/platform_api/source/conf.py new file mode 100644 index 0000000000..0cacceef97 --- /dev/null +++ b/docs/en_us/platform_api/source/conf.py @@ -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) diff --git a/docs/en_us/platform_api/source/course_info.rst b/docs/en_us/platform_api/source/course_info.rst new file mode 100644 index 0000000000..682087e8eb --- /dev/null +++ b/docs/en_us/platform_api/source/course_info.rst @@ -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
\n
\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
    \n +
  1. Example handout
    2. +
\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": "
\n +

About This Course

\n +

Include your long course description here. The long course description should contain 150-400 words.

+

This is paragraph 2 of the long course description. Add more paragraphs as needed. Make sure to enclose them in paragraph tags.

+
\n\n +
\n +

Prerequisites

\n +

Add information about course prerequisites here.

\n
\n\n +
\n +

Course Staff

\n +
\n +
\n + \n +
\n\n +

Staff Member #1

\n +

Biography of instructor/staff member #1

\n +
\n\n +
\n +
\n + \n +
\n\n +

Staff Member #2

\n +

Biography of instructor/staff member #2

\n +
\n +
\n\n +
\n +
\n +

Frequently Asked Questions

\n +
\n +

Do I need to buy a textbook?

\n +

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.

\n +
\n\n +
\n +

Question #2

\n +

Your answer would be displayed here.

\n +
\n +
\n +
" + } diff --git a/docs/en_us/platform_api/source/endpoints.rst b/docs/en_us/platform_api/source/endpoints.rst new file mode 100644 index 0000000000..5b2e8cb949 --- /dev/null +++ b/docs/en_us/platform_api/source/endpoints.rst @@ -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` + - /api/mobile/v0.5/users/{username} + * - :ref:`Get course enrollments for about a user` + - /api/mobile/v0.5/users/{username}/course_enrollments/ + * - :ref:`Get a course About page` + - /api/mobile/v0.5/course_info/{organization}/{course_number}/{course_run}/about + * - :ref:`Get updates for a course` + - /api/mobile/v0.5/course_info/{organization}/{course_number}/{course_run}/updates + * - :ref:`Get handouts for a course` + - /api/mobile/v0.5/course_info/{organization}/{course_number}/{course_run}/handouts + * - :ref:`Get videos in a course` + - /api/mobile/v0.5/video_outlines/courses/{organization}/{course_number}/{course_run} + * - :ref:`Get a video transcript` + - /api/mobile/v0.5/video_outlines/transcripts/{organization}/{course_number}/{course_run}/{video ID}/{language code} diff --git a/docs/en_us/platform_api/source/index.rst b/docs/en_us/platform_api/source/index.rst new file mode 100644 index 0000000000..33b3f583c0 --- /dev/null +++ b/docs/en_us/platform_api/source/index.rst @@ -0,0 +1,15 @@ +################################################ +edX Platform API Version 0.5 +################################################ + +.. toctree:: + :maxdepth: 2 + + read_me + preface + overview + authentication + endpoints + users + course_info + video_outlines diff --git a/docs/en_us/platform_api/source/links.rst b/docs/en_us/platform_api/source/links.rst new file mode 100644 index 0000000000..1ebb6b66ac --- /dev/null +++ b/docs/en_us/platform_api/source/links.rst @@ -0,0 +1 @@ +.. _OAuth 2.0 Standard: https://tools.ietf.org/html/draft-ietf-oauth-v2-31 \ No newline at end of file diff --git a/docs/en_us/platform_api/source/overview.rst b/docs/en_us/platform_api/source/overview.rst new file mode 100644 index 0000000000..dec9e7514d --- /dev/null +++ b/docs/en_us/platform_api/source/overview.rst @@ -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` and :ref:`course enrollments` for a user. + +* Get :ref:`course information`, :ref:`updates`, and :ref:`handouts` for courses the + user is enrolled in. + +* Get :ref:`videos` and :ref:`transcripts` for courses the user is enrolled in. \ No newline at end of file diff --git a/docs/en_us/platform_api/source/preface.rst b/docs/en_us/platform_api/source/preface.rst new file mode 100644 index 0000000000..53895c8473 --- /dev/null +++ b/docs/en_us/platform_api/source/preface.rst @@ -0,0 +1 @@ +.. include:: ../../shared/preface.rst \ No newline at end of file diff --git a/docs/en_us/platform_api/source/read_me.rst b/docs/en_us/platform_api/source/read_me.rst new file mode 100644 index 0000000000..78cfe1fd31 --- /dev/null +++ b/docs/en_us/platform_api/source/read_me.rst @@ -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 \ No newline at end of file diff --git a/docs/en_us/platform_api/source/users.rst b/docs/en_us/platform_api/source/users.rst new file mode 100644 index 0000000000..4658de8901 --- /dev/null +++ b/docs/en_us/platform_api/source/users.rst @@ -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" + } + } \ No newline at end of file diff --git a/docs/en_us/platform_api/source/video_outlines.rst b/docs/en_us/platform_api/source/video_outlines.rst new file mode 100644 index 0000000000..4163662d47 --- /dev/null +++ b/docs/en_us/platform_api/source/video_outlines.rst @@ -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. \ No newline at end of file diff --git a/lms/djangoapps/mobile_api/course_info/views.py b/lms/djangoapps/mobile_api/course_info/views.py index a9e9220de6..153d1a84d7 100644 --- a/lms/djangoapps/mobile_api/course_info/views.py +++ b/lms/djangoapps/mobile_api/course_info/views.py @@ -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,) diff --git a/lms/djangoapps/mobile_api/users/views.py b/lms/djangoapps/mobile_api/users/views.py index 1c5529ac40..79080b5142 100644 --- a/lms/djangoapps/mobile_api/users/views.py +++ b/lms/djangoapps/mobile_api/users/views.py @@ -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() diff --git a/lms/djangoapps/mobile_api/video_outlines/views.py b/lms/djangoapps/mobile_api/video_outlines/views.py index a21a88296f..2efcdf3ddd 100644 --- a/lms/djangoapps/mobile_api/video_outlines/views.py +++ b/lms/djangoapps/mobile_api/video_outlines/views.py @@ -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,)