Page Comparison

• 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).
• read up on our existing APIs: http://edx-platform-api.readthedocs.org/en/latest/
• for comparison, it is worth studying public API documentation from the big internet companies

  • https://developers.google.com/+/api/

  • 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 go to one resource to read it and then another resource to write it?
• Simple.  Keep the top-leveI resources clear and simple - focusing on what the client is looking to consume.  You can hide complexity within the parameters.
• Separation of concerns.  Do not require the consumer to know any implementation details.  For example, an API shouldn't require the client to know the inter-dependencies of fields.  Rather, all such business rules should be owned by the server.  This allows the client to be lightweight and easily maintainable in the future.
• Explicit Support Levels. APIs should make it clear whether they are experimental or more permanent as a part of their documentation.
• Discoverability. Support HATEOAS where possible.  This allows us to change our URLs without needing to worry about updating the mobile apps if the app discovers its URLs from a base URL.

Conventions

1. URL Naming