Open edX REST API Conventions

Background

This document captures the conventions to be used for all Open edX REST APIs. 

Useful reading:

• these conventions are derived from a very useful set defined by Apigee: http://pages.apigee.com/rs/apigee/images/api-design-ebook-2012-03.pdf. 

• the initial discussions about APIs were captured in API Thoughts.

• Django REST Framework version 2 documentation (we are currently using version 2.3.14, which has different APIs from the version 3).

• for comparison, it is worth studying public API documentation from the big internet companies

  • https://developers.google.com/apis-explorer

  • https://developers.facebook.com/docs/graph-api/reference/v2.2/profile

  • https://dev.twitter.com/rest/public

  • https://developer.linkedin.com/docs/rest-api

  • https://api.stackexchange.com/

  • https://instagram.com/developer/

  • https://developer.github.com/v3/

  • https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/intro_rest_resources.htm

High Level Requirements

• Consumer-Perspective. Design your API from the perspective of the consumer, NOT the perspective of your underlying implementation.  For example:

  • If the underlying implementation requires accessing multiple models or multiple apps/projects, this does not need to be reflected in a public interface.  From the perspective of the consumer, it's simply one thing they are requesting.

  • Keep CRUD operations together within its corresponding resource.  Why have the client g