One API to Rule Them All?

Convener

Steven Dunlap (@aauthor)

Attendees

feel free to add yourself

Notes

Flow of Thought

This might be able to be organized better (currently these points are chronological, not topical).

• number of requests to the API can increase load time; motivation for splitting API could be to deliver more/less payload
• versioning API could be seen as a form of API splitting
  • versions do not need to be part of the resource path
  • perhaps use headers or content-type
• **put part of what is being expected in header or query as part of the negotiation **
• use more appropriate resources the get the exact data with more reasonable defaults (e.g. /area has a whole bunch of /pois instead of /pois defaulting to have nearby Pois)
• stacking multiple API calls into one call; returning results in one large payload
• Netflix has a separate API for each device, but is that the norm?
• having an internal API can lead to having "educated developers" in which API architects/developers aren't interested in keeping the API simple
• code smell: data in API that can't be exposed to the public
• only talk to client developer through documentation
  • encourages better documentation and more though into API design instead of putting out fires
• SDKs
  • thin wrapper vs. thick wrapper
  • a thick wrapper can disguise AJAX requests as simple getters/setters and include extra logic that makes the SDK work differently than an API
  • SDKs shouldn't hide a messy API; they should support and drive the API
  • automatic SDK generation from API contract spec.
    • smelly?
    • don't have to maintain multiple code bases
    • helps spur adoption of the API
• split documentation not implementation
  • have the parts of the API that certain clients need exposed in their documentation instead of implementing splintered APIs for different use-cases
• "if you can do it in the app; you can do it in the API"
  • if the API is split, it will be very hard to keep that promise
• you can have more flexibility with a private API (make changes without worrying about breaking clients)
  • however, your flexible API could be your "beta" for the next public API
• state version vs view version
  • state version passed as content version HTTP header (reflect how the resource itself has changed)
  • view version passed in query or accepts header
• build things using your own API so that you know that it works
• push one API until become unfeasible; that that point you might have two different apps entirely
• make sure you know your users use-case stories