Just API or client SDK to help developers with API adoption

Dmitry Pavlov edited this page Aug 8, 2014 · 9 revisions

Convener

  • Glenn Block
  • Sergey Lyubimov

Attendees (add your name here)

  • Darrel Miller
  • Jorn Wildt
  • Markus Lanthaler
  • Kevin Swiber
  • Mehdi Medjaoui
  • Mike Kelly
  • Kristopher Kleva
  • Carl Zetie
  • Dmitry Pavlov

Notes

Q: The desire for SDKs, is it a symptom of bad APIs?

Pros

  • More language idiomatic / familiar to traditional developers.
  • Makes it easier for developers to just get shit done / simplifies working with the API. Don't have to educate all developers on HTTP.
  • Abstracts away / can insulate from changes to the API.

Cons

  • Versioning explosion / you now have two versions, the API and the SDK.
  • More work / maintainability of the SDK code itself
  • Can encourage bad usage patterns.
  • May not surface all of the features of the API.
  • Can get stale
  • Can be used as an excuse for poor API design / to hide the API under the covers.
  • Doesn't teach developers how the API / HTTP actually works.

Alternatives

  • Consider a Hybrid SDK / meaning helper libraries to be used with an Http Client instead of a full wrapper.
  • Release test code to educate how to use the API.
  • Have an API console
  • Educate!

General SDK tips

  • Don't make your SDK lipstick on a pig. The HTTP API must still be a good experience.
  • SDK Team should be involved with API development
  • Try to reuse existing media types / Leverage existing libraries.
  • Build SDKs in a stateless manner / closer to the underlying API.

Building SDKs that are good HTTP citizens

  • Can we build SDK clients that are less prone to break?
  • Tip: Don't hard code the URIs / have the API surface a discovery document like a Home document that the SDK uses.
  • Tip: Expose action methods in the SDK for Hypermedia links. Under the hood the code will look for links in the response / and either follow it, or throw an exception if the link is not present.

Misc

  • Should SDKs be crowd sourced, can that work?
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.