Overview¶

Fonzie is an HTTP API over the Open edX project. It has been build to open the way to new tools and interfaces in the Open edX ecosystem.

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; it can be used to start developing a front-end application that will consume Fonzie’s API (take a look at API blueprint tools).

Documentation¶

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.

Please see LICENSE.txt for details.

How To Contribute¶

Contributions are very welcome.

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

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

Reporting Security Issues¶

Please do not report security issues in public. Please email security@fun-mooc.fr.

Getting Help¶

Have a question about this repository, or about Open edX in general? Please refer to this list of resources if you need any assistance.

Install dependencies¶

Install fonzie and its dependencies in your Open edX installation with pip:

$ (sudo) pip install fonzie

Configure Fonzie¶

Once installed, Fonzie needs to be configured as a standard Django application, i.e. adding fonzie to your INSTALLED_APPS and Fonzie’s URLs to your project’s URLs.

# lms/env/private.py
INSTALLED_APPS += (
    'fonzie',
)

# Django Rest Framework (aka DRF)
REST_FRAMEWORK.update({
    'ALLOWED_VERSIONS': ('1.0', ),
    'DEFAULT_VERSION': '1.0',
    'DEFAULT_VERSIONING_CLASS': 'rest_framework.versioning.URLPathVersioning',
})

# lms/fonzie_urls.py
from lms.urls import *

urlpatterns += [
    # [...]
    url(r'^api/', include('fonzie.urls')),
]

Test your installation¶

Now that we’ve installed and configured Fonzie, it’s time to test that our API is responding! If we consider that installed Open edX LMS is served from www.mydomain.com on the port 8080, we can use the http tool (see HTTPie project) to query the API:

$ http http://www.mydomain.com:8080/api/v1.0/status/version

# http command output
HTTP/1.0 200 OK
Allow: GET, HEAD, OPTIONS
Content-Language: en
Content-Type: application/json
Date: Mon, 28 May 2018 15:37:02 GMT
Server: WSGIServer/0.1 Python/2.7.12
Vary: Accept, Accept-Language, Cookie
X-Frame-Options: ALLOW

{
    "version": "0.4.0"
}

Alternatively, you can use curl:

$ curl http://www.mydomain.com:8080/api/v1.0/status/version
{"version":"0.4.0"}

The output of this command should be a JSON payload containing the running version of Fonzie.

Pre-requisites for Fonzie contributors¶

As you might already have expected, we extensively use Docker (17.12+) and Docker compose (1.18+) in our development workflow. So, if you intend to work on Fonzie, please, make sure they are both installed and functional before pursuing this guide.

Getting started with the development stack¶

First things first, to start contributing on the project, you will need to clone Fonzie’s repository and then build the Docker-based development stack with:

# Clone Fonzie's repository
$ git clone git@github.com:openfun/fonzie.git

# Build required containers
$ make bootstrap

The make bootstrap command will:

• build an edx-platform Docker image with Fonzie installed and configured,
• run the development server
• perform Open edx LMS database migrations.

Fonzie’s API should be accessible from: http://localhost:8072/api/v1.0/

We invite you to test the status/version endpoint to ensure everything went well:

$ curl http://www.mydomain.com:8080/api/v1.0/status/version
{"version":"0.4.0"}

Development workflow¶

If you use to work with Django’s development server, you will have the same experience with a Docker-based development stack: Fonzie is installed in edit mode and mounted as a volume in the lms service. Combined with the development server, the application will be reloaded when the source code changes.

Adding dependencies¶

If your work on Fonzie requires new dependencies, you will need to:

1. Update the options.install_requires section of the setup.cfg file (or the options.extras_require.[dev,doc,...] section if it’s a development dependency),
2. Rebuild the lms service image via the make build utility.
3. Optionally perform required database migrations via:

$ make migrate