feature(api) add API blueprint workflow

## feat(api) add POC API specification

## feat(api) add /status/version implementation

- Add Django Rest Framework dependency
- Add status endpoint views & urls
- Clean-up cookie cutter example view

## feat(test) add & configure dredd

Automate API implementation testing given its specification thanks to
dredd. You will need to install it via the `yarn install` command.

TODO: update installation docs

## fix(make) fix pytest-django install

A bad regular expression used to remove django from test packages (to
let tox control it), was also removing pytest-django :(

## feat(test) add tests for status/version endpoint

## fix(requirements) switch to py3 dev env

CI quality jobs run with python 3.6 by default, so let's stick to it
and define our dependencies for python 3 instead of python 2.

## fix(compat) fix urls namespacing

Add app_name for included urls with namespace

## ci(travis) add dredd API testing

Add a new tox environment to test our API implementation with dredd

## feat(api) add Open API schema

Add drf_openapi third party dependency to auto-generate our API schema
in Open API compatible format.

The API is versioned by default (this is a good practice and its
required by drf_openapi). For now we only allow 'v1.0' API urls prefix.

## docs(core) add base documentation

* Add project installation & configuration instructions
* Update endpoints dosctring

TODO: update edx sphynx theme to a fun theme?

## fix(compat) remove Django 1.8 compatibility

Even not explicit in OpenAPI_DRF requirements, Django Rest Framework
minimal compatible release is 3.7. By using OpenAPI_drf, we are forced
to drop Django 1.8 support (it was on our roadmap anyway).

TODO: test DRF >= 3.7 compatibility with edx/edx-platform#master
(Hawthorn).

## ci(travis) fix dredd dependencies tree

Used release of nomnom dependency vanished...

.gitignore

@@ -30,6 +30,7 @@ pip-log.txt
 .cache/
 .coverage
 .coverage.*
+.pytest_cache/
 .tox
 coverage.xml
 htmlcov/
@@ -77,3 +78,7 @@ tests/__init__.py
 
 # Development task artifacts
 default.db
+
+# Node.js
+node_modules
+yarn-error.log

.travis.yml

@@ -7,7 +7,6 @@ python:
   - 3.6
 
 env:
-  - TOXENV=django18
   - TOXENV=django111
   - TOXENV=django20
 
@@ -16,19 +15,22 @@ matrix:
     - python: 2.7
       env: TOXENV=django20
   include:
-    - python: 3.6
+    - python: 2.7
       env: TOXENV=quality
-    - python: 3.6
+    - python: 2.7
       env: TOXENV=docs
+    - python: 2.7
+      env: TOXENV=spec
 
 cache:
   - pip
-  
+
 before_install:
   - pip install --upgrade pip
 
 install:
   - pip install -r requirements/travis.txt
+  - yarn install
 
 script:
   - tox

CHANGELOG.rst

@@ -3,23 +3,19 @@ Change Log
 
 ..
    All enhancements and patches to fonzie will be documented
-   in this file.  It adheres to the structure of http://keepachangelog.com/ ,
+   in this file. It adheres to the structure of http://keepachangelog.com/,
    but in reStructuredText instead of Markdown (for ease of incorporation into
    Sphinx documentation and the PyPI description).
-   
+
    This project adheres to Semantic Versioning (http://semver.org/).
 
 .. There should always be an "Unreleased" section for changes pending release.
 
 Unreleased
 ~~~~~~~~~~
 
-*
-
-[0.1.0] - 2018-02-14
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
 Added
 _____
 
-* First release on PyPI.
+* Add a POC using a schema-driven development (using
+  `API Blueprint <https://apiblueprint.org/>`_).

Makefile

@@ -46,7 +46,7 @@ upgrade: ## update the requirements/*.txt files with the latest packages satisfy
 	pip-compile --upgrade -o requirements/test.txt requirements/base.in requirements/test.in
 	pip-compile --upgrade -o requirements/travis.txt requirements/travis.in
 	# Let tox control the Django version for tests
-	sed '/django==/d' requirements/test.txt > requirements/test.tmp
+	sed '/^django==/d' requirements/test.txt > requirements/test.tmp
 	mv requirements/test.tmp requirements/test.txt
 
 quality: ## check coding style with pycodestyle and pylint
@@ -55,6 +55,7 @@ quality: ## check coding style with pycodestyle and pylint
 requirements: ## install development environment requirements
 	pip install -qr requirements/dev.txt --exists-action w
 	pip-sync requirements/dev.txt requirements/private.* requirements/test.txt
+	yarn install
 
 test: clean ## run tests in the current virtualenv
 	py.test
@@ -64,8 +65,12 @@ diff_cover: test
 
 test-all: ## run tests on every supported Python/Django combination
 	tox -e quality
+	tox -e spec
 	tox
 
+test-spec: # run tests on API specification (API blueprint)
+	yarn dredd
+
 validate: quality test ## run tests and quality checks
 
 selfcheck: ## check that the Makefile is well-formed

README.rst

@@ -1,22 +1,27 @@
-fonzie
-=============================
+Fonzie, an Open API for Open edX
+================================
 
 |pypi-badge| |travis-badge| |codecov-badge| |doc-badge| |pyversions-badge|
 |license-badge|
 
-The ``README.rst`` file should start with a brief description of the repository,
-which sets it in the context of other repositories under the ``edx``
-organization. It should make clear where this fits in to the overall edX
-codebase.
+**This project is in early-development phase, we are still experimenting on
+it.** It is intended to be community-driven, so please, do not hesitate to get
+in touch if you have any question related to our implementation or design
+decisions.
 
-edX CRUD API
+Overview
+--------
 
-Overview (please modify)
-------------------------
+Fonzie is an HTTP API over the `Open edX <https://open.edx.org/>`_ project. It
+has been build to open the way to new tools and interfaces in the Open edX
+ecosystem.
 
-The ``README.rst`` file should then provide an overview of the code in this
-repository, including the main components and useful entry points for starting
-to understand the code in more detail.
+We choose to design the API first and then propose an implementation with
+Fonzie. The current state of the API schema is available in `API blueprint
+format <https://github.com/openfun/fonzie/blob/master/fonzie-v1-0.apib>`_; it
+can be used to start developing a front-end application that will consume
+Fonzie's API (take a look at `API blueprint tools
+<https://apiblueprint.org/tools.html>`_).
 
 Documentation
 -------------
@@ -26,8 +31,8 @@ The full documentation is at https://fonzie.readthedocs.org.
 License
 -------
 
-The code in this repository is licensed under the AGPL 3.0 unless
-otherwise noted.
+The code in this repository is licensed under the AGPL 3.0 unless otherwise
+noted.
 
 Please see ``LICENSE.txt`` for details.
 
@@ -36,21 +41,21 @@ How To Contribute
 
 Contributions are very welcome.
 
-Please read `How To Contribute <https://github.com/edx/edx-platform/blob/master/CONTRIBUTING.rst>`_ for details.
-
 Even though they were written with ``edx-platform`` in mind, the guidelines
 should be followed for Open edX code in general.
 
-PR description template should be automatically applied if you are sending PR from github interface; otherwise you
-can find it it at `PULL_REQUEST_TEMPLATE.md <https://github.com/edx/fonzie/blob/master/.github/PULL_REQUEST_TEMPLATE.md>`_
+PR description template should be automatically applied if you are sending PR
+from github interface; otherwise you can find it it at `PULL_REQUEST_TEMPLATE.md
+<https://github.com/openfun/fonzie/blob/master/.github/PULL_REQUEST_TEMPLATE.md>`_
 
-Issue report template should be automatically applied if you are sending it from github UI as well; otherwise you
-can find it at `ISSUE_TEMPLATE.md <https://github.com/edx/fonzie/blob/master/.github/ISSUE_TEMPLATE.md>`_
+Issue report template should be automatically applied if you are sending it from
+github UI as well; otherwise you can find it at `ISSUE_TEMPLATE.md
+<https://github.com/openfun/fonzie/blob/master/.github/ISSUE_TEMPLATE.md>`_
 
 Reporting Security Issues
 -------------------------
 
-Please do not report security issues in public. Please email security@edx.org.
+Please do not report security issues in public. Please email security@fun-mooc.fr.
 
 Getting Help
 ------------
@@ -65,12 +70,12 @@ refer to this `list of resources`_ if you need any assistance.
     :target: https://pypi.python.org/pypi/fonzie/
     :alt: PyPI
 
-.. |travis-badge| image:: https://travis-ci.org/edx/fonzie.svg?branch=master
-    :target: https://travis-ci.org/edx/fonzie
+.. |travis-badge| image:: https://travis-ci.org/openfun/fonzie.svg?branch=master
+    :target: https://travis-ci.org/openfun/fonzie
     :alt: Travis
 
-.. |codecov-badge| image:: http://codecov.io/github/edx/fonzie/coverage.svg?branch=master
-    :target: http://codecov.io/github/edx/fonzie?branch=master
+.. |codecov-badge| image:: http://codecov.io/gh/openfun/fonzie/coverage.svg?branch=master
+    :target: http://codecov.io/gh/openfun/fonzie?branch=master
     :alt: Codecov
 
 .. |doc-badge| image:: https://readthedocs.org/projects/fonzie/badge/?version=latest
@@ -81,6 +86,6 @@ refer to this `list of resources`_ if you need any assistance.
     :target: https://pypi.python.org/pypi/fonzie/
     :alt: Supported Python versions
 
-.. |license-badge| image:: https://img.shields.io/github/license/edx/fonzie.svg
-    :target: https://github.com/edx/fonzie/blob/master/LICENSE.txt
+.. |license-badge| image:: https://img.shields.io/github/license/openfun/fonzie.svg
+    :target: https://github.com/openfun/fonzie/blob/master/LICENSE.txt
     :alt: License

docs/conf.py

@@ -368,7 +368,7 @@ def get_version(*file_paths):
 #  dir menu entry, description, category)
 texinfo_documents = [
     (master_doc, project_title, documentation_title,
-     author, project_title, 'edX CRUD API',
+     author, project_title, 'An Open API for Open edX',
      'Miscellaneous'),
 ]
 

docs/getting_started.rst

@@ -7,10 +7,68 @@ below is executed within the virtualenv.
 .. _virtualenv: https://virtualenvwrapper.readthedocs.org/en/latest/
 
 
+Pre-requisites
+--------------
+
+We are using `Dredd <http://dredd.readthedocs.io/en/latest/>`_ to test our API
+implementation. It requires `Node.js <https://nodejs.org/en/>`_ to run and we
+are using `Yarn <https://yarnpkg.com/en/>`_ to install it. So make sure both
+``node`` and ``yarn`` are installed and functionnal before pursuing this
+installation.
+
 Install dependencies
 --------------------
-Dependencies can be installed via the command below.
+
+Dependencies can be installed via `pip` in your project's virtual environment:
+
+.. code-block:: bash
+
+    # Create a python 2.7 virtual environment
+    $ virtualenv venv
+
+    # Activate your virtual environment
+    $ source venv/bin/activate
+
+    # Install fonzie and its dependencies in your virtualenv
+    (venv) $ pip install fonzie
+
+Alternatively, if you intend to work on this project, clone the repository first and then
+install requirements _via_ the command below:
 
 .. code-block:: bash
 
-    $ make requirements
+    $ git clone git@github.com:openfun/fonzie.git
+    (venv) $ make requirements
+
+Configure Fonzie
+----------------
+
+Edit the settings of your project  (_e.g._ ``my_project/settings.py``) by adding
+``fonzie`` to your ``INSTALLED_APPS`` and configure Django Rest Framework (_aka_
+DRF) API versioning support as follows:
+
+.. code-block:: python
+
+    # my_project/settings.py
+
+    INSTALLED_APPS = (
+        # [...]
+        'fonzie',
+    )
+
+    # Django Rest Framework (aka DRF)
+    REST_FRAMEWORK = {
+        'ALLOWED_VERSIONS': ('1.0', ),
+        'DEFAULT_VERSION': '1.0',
+        'DEFAULT_VERSIONING_CLASS': 'rest_framework.versioning.URLPathVersioning',
+    }
+
+And finally, configure Fonzie urls for your project:
+
+.. code-block:: python
+
+    # my_project/urls.py
+    urlpatterns = [
+        # [...]
+        url(r'^api/', include('fonzie.urls')),
+    ]

docs/index.rst

@@ -4,8 +4,8 @@
    contain the root `toctree` directive.
 
 fonzie
-===============================
-edX CRUD API
+======
+An Open API for Open edX
 
 Contents:
 
@@ -15,7 +15,6 @@ Contents:
    readme
    getting_started
    testing
-   internationalization
    modules
    changelog
 
@@ -26,4 +25,3 @@ Indices and tables
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
-

docs/testing.rst

@@ -3,9 +3,9 @@
 Testing
 =======
 
-fonzie has an assortment of test cases and code quality
-checks to catch potential problems during development.  To run them all in the
-version of Python you chose for your virtualenv:
+fonzie has an assortment of test cases and code quality checks to catch
+potential problems during development.  To run them all in the version of Python
+you chose for your virtualenv:
 
 .. code-block:: bash