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
- How the APIs are used.
- How you want to govern the APIs.
- 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.
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 development team for the customer reengagement initiative. He previously led the modernization drive for legacy services within the company, as well as the testing effort for the API team of Ancestry.com where he was responsible for educating and defining test strategies for the team. During his time with the company, Seng Lin 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.