0

(Please let me know if this question belongs to a different stackexchage site)

I have a use case where the clients of my service have to call some APIs exposed in the service. The API specification model being used allows for auto-generation of client bindings for different languages.

I need to provide an enhanced functionality around some of the APIs and that custom code sits around the calls to the API. Instead of expecting every client to write this code on their own, I would like to provide this as a wrapper around the auto-generated client library. I understand that this needs to be done for different languages to be supported (the list if 2-3 in my case).

In general, is this a good choice to make? Are there any other alternatives?

Please let me know if more details are needed.

Vikdor
  • 23,934
  • 10
  • 61
  • 84

1 Answers1

1

Generating clients from some kind of API Definition (like OpenAPI) and shipping it with other code is a very common pattern and i've used and created such clients in the past. For the consumers of your API this has some clear advantages: He doesn't have to generate the client (depending on the used technologies is sometimes painful), he benefits from the maintenance done by the provider (and others), and uses the official way to interact with the API.

In such a client there are three main packages which should separated and independent from each other:

  • The generated client
  • Code which eases the usage of the generated client
  • Other Code (i.e. utilities that abstract or simplify common interactions, provide domain logic required on the client side etc)

If these are separated it is very easy for a consumer to pick the pieces he wants to use.

The main disadvantage is that you have to implement and maintain multiple clients for your API. Depending on the size of your API, the supported platforms and environments the clients are used in, this can be a very elaborate task. Also keep in mind that providing a decent client library requires a good understanding of the target platforms and environments. Otherwise your client library might not be accepted by other developers.

In general generated code if often not that "natural" and "nice". For example the generated identifiers might not follow the conventions of the platform or it requires the usage of over complicated constructs like factories to create a simple object. Often the generators can be tweaked, but this adds to the required effort.

All these efforts often add up, so that even big API Providers struggle to provide good client libraries for many platforms.

There are two alternatives:

  • Only provide a API Definition
  • Handcraft a client

The first alternative gives the consumer the freedom to choose the way he wants to use your API. But given a good API Definition (which is hard to write), it is relatively easy to do so. In this case it is not possible to provide some additional code to the client. But in general you should aim for dumb clients and avoid clients to perform business logic.

A handcrafted client is best suited if you aim for a limited number of platforms on which you want to provide the best possible experience for the consumers. Further you can implement all kinds of other stuff. But even for a single platform this might be a huge effort.

gregor
  • 4,733
  • 3
  • 28
  • 43