So, you want to share your super awesome system with the world. You have it all figured out. You implemented it as a web service, and you have exposed the necessary APIs as HTTP endpoints. Your hope is that people will start to leverage those endpoints and begin to build awe-inspiring apps that will further increase the value of your web service API.

Of course, there are decisions you need to make, such as protocols to use, security concerns, documentations, tutorials, support and the whole shebang.

There is one contentious decision that you as a developer have to make: Should a client library be provided for developers to use your web service? Or is exposing an endpoint sufficient for developers to start building applications?

We can go on for hours debating the pros and cons for providing and omitting client libraries. The argument is very similar to Amazon proving that REST doesn’t matter for Cloud APIs. There are standards that we can follow and that are backed by an army of proponents. However, as with most of my blog articles, I came to the conclusion that the decision depends on

  1. How the APIs are used.
  2. How you want to govern the APIs.
  3. Who uses it?

In support of Client Libraries

Popular APIs include Google, Flickr, YouTube, Twitter and Amazon as they provide developer SDKs that make it really easy to implement these APIs in application across a myriad of platforms and languages. The motivation for this is to actually provide a lower learning curve to developers to get onboard the API platform.  Evidently, the underlying API calls which have been abstracted are pretty complex.

Another argument for client libraries would be to provide a control point; a programmable interface that provides a logical abstraction to represent the actions that will be performed. A client library acts as a proxy between the application and the actual endpoint. By mediating traffic between the application and the endpoint, the proxy is able to address cross cutting concerns such as analytics collection, traffic control and even access rights. As Sam Ramji pointed out, API clients are necessary for the sustained growth of web and cloud API usage.

Without a client library or an SDK, a developer is required to provide extra logic to communicate with a service endpoint. There is no forcing function for a standard or common way to access the endpoint (unless documented explicitly). This becomes extremely critical in an enterprise that is comprised of a multitude of web services that as a whole represent the entire company asset. The absence of a framework allows developers the freedom to implement his or her own way of addressing the same concerns; leading to a plethora of different coding styles. The existence of an SDK allows the service to establish a common programming pattern and model that are part of the nature and identity of the service.

Argument against Client Libraries

If different systems require a different client library or SDK, then a  client that uses a multitude of services would eventually be overwhelmed with the sheer number of different models and programming patterns (e.g. imagine forcing a developer to use Unity just for instantiating an object, when the developer has no interest in using IoC pattern).

If an API endpoint is simple, with straightforward message formats, a common tool/library could be built to provide a communication mechanism for accessing and parsing messages to and from API endpoints.

Also, SDKs and client libraries are usually maintained by the endpoint developers. Resources have to be dedicated to support the development toolset (aka SDKs/client libraries) every time a new iteration of service is rolled out. The team needs to evaluate if such a commitment can be maintained over a long period of time. Furthermore, this maintenance may include updating SDKs/client libraries across multiple languages and environments.

Following the above reason, from the perspective of the client, each library coded for a service is written by someone else. A great trust is needed to rely on the skills and experience of the library developer. It is also possible that the client libraries may not even be properly maintained, updated or tested.

Conclusion

The current trend is to architect your system into tiers, so that you can distinguish business logic, processing and storage implementations. This calls for abstraction of services behind service client APIs, or the usage of SDKs. However, this should not always be the de facto solution for abstraction services. Over engineering only complicates matters, and sometimes the simplest solution is the most viable answer.

Using all of the above arguments, I hope you are able to make the right decision for your service, which would also attract the right developer for your project.

Comments

  1. Hey,

    I’m glad that I found a great place with lot of information. Now that you have mentioned the APIs argument, will it be possible to write more about the Testing of these APIs?

    I’ve read thru your bio and you must be very good at the TESTing of the APIs with various patterns & techniques. Hence, please do one write up about this.

    Regards,

    • Seng Lin Shee

      Thank you for your comment, Chakravarthy. We are glad that you find this blog site useful. Feel free to browse the rest of the site in case you find other blog articles which may relate your interest.

      Thanks for the suggestion. Appreciate it. I will take note of that. I have written an article about Acceptance Testing in my team. Do look it up here. That is one technique that can be used for API testing.

      Do follow us using our social links, and we will keep you posted on any new articles.

  2. adam carbone

    So with all this talk about proper api design, is there every any intent for ancestry.com to expose an api to be able to access at least the data associated with your family tree?

    • Seng Lin Shee

      Thanks for your question. We do not have a publicly available external API at this time, but who knows what the future might bring. We’re always exploring ways that will help serve on our mission of helping everyone discover, preserve, and share their family history.

Join the Discussion

We really do appreciate your feedback, and ask that you please be respectful to other commenters and authors. Any abusive comments may be moderated. For help with a specific problem, please contact customer service.