Posted by on November 27, 2013 in API, Development, Mobile, Technical Management

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.

About Seng Lin Shee

Seng Lin Shee is a Sr Software Engineer, leading the modernization effort for legacy services within the company. Shee previously led the testing effort for the API team of Ancestry.com where he was responsible for educating and defining test strategies and direction of the testing effort for the team. During his time with the company, Shee has introduced behavioral and test driven design methodologies into the team, and also contributed to the design of the continuous delivery pipeline within the company. Prior to Ancestry.com, Shee was a Software Development Engineer in Test at Microsoft. He holds a PhD in Computer Science & Engineering from The University of New South Wales, Sydney, Australia.

2 Comments

Chakravarthy 

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,

December 6, 2013 at 8:19 am
    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.

    December 6, 2013 at 6:47 pm

We really do appreciate your feedback, and ask that you please be respectful to other commenters and authors. Any abusive comments may be moderated.

Commenting is open until Wednesday, 11 December 2013