CODEWITHSUNDEEP
restsdkversioning
Emil
Emil

Reputation: 13799

REST API versioning and sdk

How do services like github,twilio,algolia,stormpath maintain rest api's along with SDK's for different languages? Do they generate such code using tools like enunciate or are they maintaining the client code themselves? I guess for github ,they are open sourced client libraries. My questions are:

  1. How to sync between rest api changes and corresponding SDK changes.

  2. What are the best practices for versioning of rest apis,as well as their sdk's ?What are the common pitfalls one must be aware of?

Upvotes: 1

Views: 451

Answers (1)

redox
redox

Reputation: 2319

At Algolia we’ve developed a dozen of API clients on top of our REST API. Honestly, I must say we suffered a lot to create all of them /o\ I hope the following bullet points will help:

Why did we create our own API clients instead of just using libraries/tools to generate them (which is pretty common for REST API clients)?

  • be able to reach a 99.99% SLA, we decided to implement a “retry-strategy” in our API clients -> the Algolia index is always replicated on 3 machines -> if one goes down the API client will retry on the other ones -> this cannot be handled by generic libraries
  • to reach optimal performances, we wanted to be sure we control the way the HTTP keep alive works -> most of generic libraries doesn’t handle that as well
  • we wanted to force HTTPS as soon as possible

How did we proceed?

  • at the beginning, we were not super fluent in all those languages; so we started to look at other API clients implemented in each language to understand best practices
  • we got the help from 1 guy for Node.js and 1 for python
  • but it was really not OK until we decided to move all of them to Travis.CI + plug code coverage to reach 80-95% code coverage + automated tests -> obviously, we spot a lot of bugs :)
  • as soon as we release a new feature, we need to update all our API clients -> pretty painful…
  • to ease the README generation, we’ve developed a small tool generating the README for all languages. It’s super Algolia-specific but you can have a look at https://github.com/algolia/algoliasearch-client-readme-generator -> pretty painful to bootstrap as well :)

Things we learned:

  • maintaining all of them ourself make them act exactly the same, whatever the language -> super appreciable from a customer POV
  • if your community is building API clients, that’s cool; but they may not go so deep in the tests -> we’re testing ALL features in ALL API clients -> quality
  • we would do the same again if we needed to

Upvotes: 2

Related Questions