API Design – Discussion

 

Hand-over Points

In this approach, the contract is expressed in the form of an API description. In each phase of the approach, an API description is either created, refined or used: the API description is the red thread connecting all the steps of the approach.

When can the API description be handed over to pilot consumers? Pilot consumers need to be patient and they need to be aware of the fact that their clients might break, since the API description might still change. The earliest point in time at which a hand-over of the API description makes sense, is after the architectural and detailed design phase has been finished, the API description has been created and has been simulated successfully.

When is the API description finished? The API description is only really finished, when the API has been published, in the final phase of the approach. After publishing the API, the API description is frozen and cannot be changed without breaking potential clients.

Pre-Work vs. Actual Work

When you look at the proposed approach, you can see that a lot of “pre-work” is done, before the actual implementation for production starts. Is this a waste of time? No, this pre-work is required so the API is stable and does not need to be changed shortly after publication. Once an API is published, an implicit (and sometimes even explicit) contract between API provider and API consumer is made. In this contract, the API provider agrees to support the API for some time into the future, and will not make any changes that might break the client.

For the consumers this means that they can rely on the API to be around for a while and thus dare to build solutions, which rely on this API.

For the API provider, however, this contract is constraining. The API provider needs to support the API. Changes are not possible on the published API. If the API provider notices too late (i.e. after publishing) that the API should actually look and behave differently, the existing API cannot just be updated, since this would break the existing clients. Compared to this scenario, both parties are actually better off, when investing into the “pre-work” for design and verification, before beginning the “actual work” of implementation.