Should I provide client libraries in some select languages along with the APIs themselves?

Question

Say I have created a web service based on RESTful APIs. Does it make sense to also provide users with a client library for the API in some select languages which are likely to be the most used ones? By client library, I mean a thin wrapper around all the API calls, so that the users can call methods in their language and get objects in their language, which they can manipulate easily.

If I do not provide a client, users will create their own versions of the clients, and will have to bother with creating their own versions of the data model objects, and also have to deal with decisions like which HTTP library to use.

If I do provide a client, there is first the question of which languages do I support. Moreover, it might become difficult to maintain consistency between the API and the client libs. Also, there is the argument that the API is redundant if I provide a client library. I can simply provide the client library alone. Then I need to maintain the API contract at only one place instead of two.

I am a bit under pressure to provide the client library because many of the users are apprehensive about using the API (most likely because they'll have to write this library themselves if they are to use the API). Which is the best way to go? Are there other pros and cons I am missing? Appreciate any advice/anecdotes.

Answer 1

Many of the organisations offering RESTful APIs also offer up some client code, but they also provide the full API separately. I think there's only a few sensible combinations:

1. API and client
2. API only
3. Client-only

I've ordered those in terms of preference, with API plus client being the most favoured. This is because, unless your API documentation is perfect, it probably won't be completely clear how you would string certain operations together to do something useful. This is where your client code comes in handy.

In general, support the most common languages as clients. Personally, I'd want to be creating libraries for (not in any particular order):

• PHP
• Ruby
• Python
• .NET
• Java
• Node.JS

Anything else is probably superfluous, or could be built by inspecting the code of your existing clients. It's probably wise to open-source the clients, even if not the rest of your code, so that the community can provide bug fixes and extra features. You've not told us a great deal about your exact scenario so it's difficult to say with any certainty whether that would be appropriate in this case.

Answer 2

It depends on how many users there will be for each language, and how long it takes you to write them. If you only have a handful of users then there's little point IMO. If you have (or expect to have) 1000s of users (and it's financially viable from a business point of view), then it's probably worth doing.

Will the client library be a simple API wrapper, or will you provide more functionality over time? Also, you may have multiple versions of each client library to maintain.

You may have to become an 'expert' to provide a library that conforms to the very different idioms for for each language.

Don't forget the maintenance side of things. Tweaks to APIs may need tweaks for every supported library.