...
- Nice: Do not expose database IDs where possible (Must for external APIs, per dev ops)
- Must: edX resource identifiers
Users should be referenced by username.
- Courses runs should be referenced via course run keys (eg. course-v1:edX+BlendedX+1T2018)
- Catalog courses should be referenced via a catalog UUID.
- Course blocks should be referenced via usage keys (eg. block-v1:org+course+run+type@sequential+block@2aa6fc9d8278)
- Explicit Filters
- Model system resource URL schemes as if all resources are available to all users
- Include all necessary filters in the URL such that any user could theoretically access the resource
Separate filtering and authorization – ie, do not return different resource representations via the same URL based on the requesting userAnchor username username Example 1: Choose "/profiles/john_harvard" versusover "/profile"
Example 2: Choose "/courses?username=john_harvard" versusover "/courses"
Remember, it's entirely possible that "/profiles/john_harvard" or "/courses?username=john_harvard" could be requested by the "administrator" user
- Several benefits exist from an explicit filtering approach:
- Ensures resources/results are individually-addressable
- Enables discovery/sharing of resources, among other potential uses
- Resource filtering mechanisms can be modified without impacting authorization mechanisms
- Intermediate network gear can cache resource representations to improve performance (for open/unprotected resources)
- Composite Resource (with multiple dimensions)
- If an endpoint represents a relationship among multiple dimensions, the dimensions can be specified in the following ways:
- As filter parameters:
/api/enrollments/v1/enrollments/?user={username}&course={course_id}
- As comma-delimited resource keys in the URL:
/api/enrollments/v1/enrollments/{username},{course_id}
- As a UUIDs to uniquely identify the relationship:
/api/enrollments/v1/enrollments/{enrollment_id}
...