Versions Compared

Old Version 86

changes.mady.by.user Nimisha Asthagiri

Saved on

compared with

New Version 87

changes.mady.by.user Chintan Joshi

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

  • Resource name

    • Keep verbs out of the base URL
    • Must: Use plural rather than singular nouns
    • Must: Use concrete (e.g., blogs, videos, news) rather than abstract (e.g., items, assets) names
    • Must: Use Python conventions: use_underscores instead of CamelCase
  • Verbs

    • When no resource is involved, be direct and use Verbs instead of Nouns (p 19).  But only when absolutely necessary as we try to use nouns as much as possible.

    • /convert?from=EUR&to=CNY&amount=100

    • Make it clear in your API documentation that these “non-resource” scenarios are different.

See list of example APIs at the end of this document.

...

  • 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 should be referenced via course keys
    • Course blocks should be referenced via usage keys
  • 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
    • Anchor
      username
      username
      Separate filtering and authorization – ie, do not return different resource representations via the same URL based on the requesting user 
      • Example 1:  "/profiles/john_harvard" versus "/profile"
      • Example 2:  "/courses?username=john_harvard" versus "/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}

...

  • Must: Sweep complexity behind the ‘?’  (e.g., GET /dogs?color=red&state=running&location=park) (p 9)

  • fields parameter - Allow clients to specify/filter the fields in the response by supporting a fields parameter as a comma-delimited list. 
    "Partial Response allows you to give developers just the information they need." (p 16)

    No Format
    /dogs?fields=name,color,location
/dogs?fields=title,media:group(media:thumbnail)


  • expand parameter - Allow clients to request including data from other resources using the expand parameter as explained further in #expand. 
  • requested_fields parameter - Allow clients to request additional optional fields that will be added to the response.  (e.g. GET /comment?requested_fields=author_profile_image,endorse_profile_image)
  • text_search parameter - Allow clients to perform text-based search using this parameter.  (p 22)
    • global: /search?text_search=fluffy+fur
    • scoped: /owners/5678/dogs?text_search=fluffy+fur
    • formatted: /search.xml?text_search=fluffy+fur

...

...

...