Page Comparison

...

• We use the conventions established by DRF, with some extra fields:

  • next: A URL to the next page, or null.

  • previous: A URL to the previous page, or null.

  • count: The total number of items.

  • num_pages: The total number of pages.

  • results: List of results.

• The query parameters are as follows:

  • page - the page of results (zero indexed)

  • page_size - the number of results to return per page

  • sort_order - a string indicating the desired order (no direction modifiers)

8. Documentation

• Document each end point using the conventions described below: #docstrings

• Work with hoeberR (Deactivated) to update the edX platform API documentation (http://edx-platform-api.readthedocs.org/en/latest/)

• Either Swagger or Apiary can be used to generate API documentation.  Although Swagger is preferred by the Mobile team, it first requires us to complete our upgrade of django.

9. Discoverability

• Use hyperlinks (with absolute URLs) to represent (primary/foreign) keys.

• When there are links to other resources, we should have a hyperlink in the response.

10. Multiple Formats

• JSON as the default format

• Clients can request different formats by specifying the "Accept" header

• The server should always include a "Content-Type" header which specifies the format of the data being returned

11. Authentication

By convention, our REST APIs support the following two authentication schemes:

• OAuth2 - for mobile clients and micro-services

• Session-based authentication - for mobile webviews and browser clients 

12. Serialization Conventions

• Dates and Timestamps

  • Should be serialized to strings in the ISO 8601 standard format

  • Timestamps should include explicit timezone offsets

  • UTC timestamps are preferred

To Be Discussed

• Consolidate all API requests under one API subdomain.  (p 23)

  • And also do Web redirects for common names

...

APIs can support expanding related objects, e.g. the team API optionally includes user profile information for each member.  This is preferable to requiring the client to make multiple subsequent AJAX calls.

For example, there can be three levels for a related object (using "username" as an example):

• Returning just the id

"username": "andya"

• Returning an object containing the id and a URL to get more details

"user": {
  "username": "andya",
  "url": "https://openedx.example.com/api/user/v1/accounts/andya"
}

• Returning an object containing the expanded details

"user": {
  "username": "andya",
  "country": "UK",
  "profile_image": {
    "has_image": True,
    "image_url_full": "http://my-image-storage.net/media/profile_images/123456789_500.jpg",
    "image_url_large": "http://my-image-storage.net/media/profile_images/123456789_120.jpg",
    "image_url_medium": "http://my-image-storage.net/media/profile_images/123456789_50.jpg",
    "image_url_small": "http://my-image-storage.net/media/profile_images/123456789_30.jpg",
  },
  ...
}

By default:

• For objects that have their own APIs, use option (b) and return both an id and a URL

• For other objects, use option (a) and just return the id

• Support a query parameter indicating an optional list of objects to be expanded: e.g. ?expand=user,team

...

edX API docstrings serve two purposes:

1. They are interpreted by DRF to provide dynamic API documentation

   • e.g. https://courses.edx.org/api/user/v1/accounts/AndyA

   • See the DRF documentation for more details: http://tomchristie.github.io/rest-framework-2-docs/topics/documenting-your-api

2. They are compiled by the Sphinx Napoleon extension to be included in our published API documentation set

   • http://edx-platform-api.readthedocs.org/en/latest/

These two tools put constraints on the format of the docstring, so we developed the following compromise that should work for both:

• Add the endpoint documentation as a docstring on your DRF view class

  • Note: individual method implementation docstrings are not currently used, but are still worth including for readers of the code.

• Use Markdown format, and do not include any HTML as it will render incorrectly in one or both tools

• Use double asterisks (bold) around headings

• Be careful with the indentation as the Sphinx generation for ReadTheDocs is very finicky

• Provide at least the following sections:

  • Use Cases

  • Example Requests
    

  • Response Values for GET, Response Values for PUT etc if you implement multiple methods)

Here is a representative docstring (from https://github.com/edx/edx-platform/blob/master/common/djangoapps/enrollment/views.py#L67):

...

...

• The edX API Documentation Tools are installed into LMS, CMS, Registrar, and some other services.

  • They can easily be added to other services.

  • They are not yet installed via the IDA cookiecutter (https://openedx.atlassian.net/browse/TNL-8167).

• The doc tools will auto-generate documentation for existing APIs under /api/ by looking at the path, serializers, and other metadata it can discern from the code.

  • For example, see https://courses.edx.org/api-docs/. Most of those are auto-generated.

• Once installed, the doc tools can be used to enrich, modify, or exclude documentation for particular API views.

  • For example, see this usage of the @edx_api_doc_tools.schema decorator to document a GET endpoint.

• Many API views still use long, metadata-filled, formatted docstrings to document APIs.

  • In the past, this was our strategy for generating API documentation; however, the tools we previously used to generate structured documentation from docstrings are no longer supported.

  • These long docstrings are much better than nothing! However, to avoid duplicating information, these docstrings can be shortened once the endpoint is documented using the edx-api-doc-tools library.

9. Discoverability

• Use hyperlinks (with absolute URLs) to represent (primary/foreign) keys.

• When there are links to other resources, we should have a hyperlink in the response.

10. Multiple Formats

• JSON as the default format

• Clients can request different formats by specifying the "Accept" header

• The server should always include a "Content-Type" header which specifies the format of the data being returned

11. Authentication

By convention, our REST APIs support the following two authentication schemes:

• OAuth2 - for mobile clients and micro-services

• Session-based authentication - for mobile webviews and browser clients 

12. Serialization Conventions

• Dates and Timestamps

  • Should be serialized to strings in the ISO 8601 standard format

  • Timestamps should include explicit timezone offsets

  • UTC timestamps are preferred

To Be Discussed

• Consolidate all API requests under one API subdomain.  (p 23)

  • And also do Web redirects for common names

Anchor
#expand #expand

Expanding referenced objects

APIs can support expanding related objects, e.g. the team API optionally includes user profile information for each member.  This is preferable to requiring the client to make multiple subsequent AJAX calls.

For example, there can be three levels for a related object (using "username" as an example):

• Returning just the id

"username": "andya"

• Returning an object containing the id and a URL to get more details

"user": {
  "username": "andya",
  "url": "https://openedx.example.com/api/user/v1/accounts/andya"
}

• Returning an object containing the expanded details

"user": {
  "username": "andya",
  "country": "UK",
  "profile_image": {
    "has_image": True,
    "image_url_full": "http://my-image-storage.net/media/profile_images/123456789_500.jpg",
    "image_url_large": "http://my-image-storage.net/media/profile_images/123456789_120.jpg",
    "image_url_medium": "http://my-image-storage.net/media/profile_images/123456789_50.jpg",
    "image_url_small": "http://my-image-storage.net/media/profile_images/123456789_30.jpg",
  },
  ...
}

By default:

• For objects that have their own APIs, use option (b) and return both an id and a URL

• For other objects, use option (a) and just return the id

• Support a query parameter indicating an optional list of objects to be expanded: e.g. ?expand=user,team

Anchor
review-process review-process

Review Process

...