Open edX REST API Conventions
- 1 Background
- 2 High Level Requirements
- 3 Conventions
- 3.1 1. URL Naming
- 3.2 2. Identifying Resources
- 3.3 3. HTTP Verbs
- 3.3.1 A note on HTTP PATCH
- 3.4 4. URL Parameters
- 3.5 5. Errors
- 3.6 6. Version
- 3.7 7. Pagination
- 3.8 8. Documentation
- 3.9 9. Discoverability
- 3.10 10. Multiple Formats
- 3.11 11. Authentication
- 3.12 12. Serialization Conventions
- 3.13 To Be Discussed
- 4 Expanding referenced objects
- 5 Review Process
- 6 Example APIs
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
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