Internet2 Confluence has been upgrade to 7.19.20. Questions? Contact techsupport@internet2.edu.
Functional Requirements
- Full I18N/L10N support
- Server-side functionality should almost never be optional (to facilitate interoperability)
- Client-side functionality may be optional when interoperability is not impeded
Discussion Items
- 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
- RESTful vs RESTlike
- "Be as simple as possible, clients will adapt" vs "Be as flexible as possible to facilitate integration for all clients"
- "There is only one way to do it" vs "There are multiple reasonable ways to do it"
- Pagination approach
- JSON vs XML vs etc, and means of conveying (URI .extension vs Accept header)
- UTF-8/equivalent
- Use of identifiers and references (serial vs UUID vs URL vs name-based-lookup, etc)
- Style decisions
- Single vs Plural (/user vs /users)
- under_scores vs usingCaps
Technical Requirements
- Content Type Negotiation
- Response formats are negotiated via an
Accept:
header, not via URI notation (.json
)
- Date and Time Representations
- Dates and times are in ISO 8601 format, with restrictions
- Year is four digits (
YYYY
)
- Year+Month is
YYYY-MM
- Year+Month+Day is
YYYY-MM-DD
(ie: dashes are required)
- Times are always in UTC
- Time is
HH:MM:SSZ
- Fractional seconds are optional (
HH:MM:SS.SSSSZ
)
- Date+Time is
YYYY-MM-DDTHH:MM:SSZ
- 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
{"serverDuration": 91, "requestCorrelationId": "88c0b59b021f49b7"}