Functional Requirements

  1. Full I18N/L10N support
  2. Server-side functionality should almost never be optional (to facilitate interoperability)
  3. Client-side functionality may be optional when interoperability is not impeded
Discussion Items
  1. Proposed CIFER-API work style:
    • Treat these as guidelines, and if we want to deviate in any particular case, just do it consciously and with some discussion
      • Someone volunteers to take on role of "guideline watchdog" to make sure we're conscious when we deviate
  1. RESTful vs RESTlike
  2. "Be as simple as possible, clients will adapt" vs "Be as flexible as possible to facilitate integration for all clients"
  3. "There is only one way to do it" vs "There are multiple reasonable ways to do it"
  4. Pagination approach
  5. JSON vs XML vs etc, and means of conveying (URI .extension vs Accept header)
  6. UTF-8/equivalent
  7. Use of identifiers and references (serial vs UUID vs URL vs name-based-lookup, etc)
  8. Style decisions
    1. Single vs Plural (/user vs /users)
    2. under_scores vs usingCaps

Technical Requirements

  1. Content Type Negotiation
    1. Response formats are negotiated via an Accept: header, not via URI notation (.json)
  2. Date and Time Representations
    1. Dates and times are in ISO 8601 format, with restrictions
    2. Year is four digits (YYYY)
    3. Year+Month is YYYY-MM
    4. Year+Month+Day is YYYY-MM-DD (ie: dashes are required)
    5. Times are always in UTC
    6. Time is HH:MM:SSZ
    7. Fractional seconds are optional (HH:MM:SS.SSSSZ)
    8. Date+Time is YYYY-MM-DDTHH:MM:SSZ
    9. Acceptable formats are defined on a per-attribute basis in the core schema

Highlights from the Apigee Web API Design document

RESTful URLs
  • Nouns, not verbs
    • Plural nouns over singular (just pick one and stick with it; CIFER Groups API uses plural?)
    • Concrete vs. abstract: if it's media, don't use "../items", use "../videos", "../blogs",...
  • two URL patterns: ../dogs ../dogs/1435
    • Hide complexity behind the "?"
      • ../dogs?color=red&state=running&location=park
  • Handling relationships between resources: ../owners/8656/dogs
    • try to stick with a small number of levels
  • Support pagination of results: /dogs?limit=10&offset=0
  • Keep versioning to simple integers and place at front of url: ../v1/dogs
  • Allow subsetting of resource elements:
    • ../dogs?fields=name,color,location
  • Content type: explicit ../dogs.json; default json
    • If type is explicit, override Accept header
  • Searching: ../dogs/search?q=fluffy
  • camelCase for attribute names
  • Complement the API with an SDK
HTTP verbs for actions
  • POST Create
  • GET Read
  • PUT Update
  • DELETE Delete
Error handling:
  • Use a limited set of HTTP status codes, maybe just these ten:
    • 200: OK
    • 201: Created
    • 304: Not modified
    • 400: Bad request
    • 404: Not found
    • 401: Unauthorized
    • 403: Forbidden
    • 409: Conflict w existing state of resource
    • 412: Precondition failed
    • 500: Internal server error
  • No labels