Step 19: Convenience Is not an -ility ~ Gregor Hohpe

This is the Nineteenth Step towards gaining the Programming Enlightenment series. If you didn’t learn the Eighteenth Step, read it.

Equally Good API isn’t built right the first time. Even more, it’s difficult to change it later. Don’t even put into the picture the pain to support for the API changes.

What is API?

It stands for Application Programming Interface.

It is a set of definitions, protocols and tools for building application software. A good API makes it easier to develop software by providing all the building blocks.

Why do we need API?

• It allows the programmer tools to develop software by accessing the APIs.

List of Java API,  Android API

• Companies allows their customers access to their products which they sell it through APIs.

GitHub APIs, Openweathermap APIS, Google Maps APIs

Why we need to design a good API?

• We expose ourselves through API, and our customer consumes it. They should be able to use it effortlessly.
• Once the consumer starts consuming it, any design changes in the API will be very hard to swallow as that would be a heavy change in the consumer side.
• If by any chance we need to change it, we need to have a back compatibility support and slap it with @Deprecated tag.

What should an API do?

• The metaphor of API as a language can guide us towards better design decisions.
• An API should provide an expressive language, which will direct the consumer to what the API does with it’s vocabulary.
• An API should be consistent and well thought out, so that it’s easier to understand.
• An API should be designed for the ease of CONSUMER rather than the designers.

TL;DR Donot design API for your convenience. Think about consumers FIRST.

Go to the series.

Go to Eighteenth Step

Go to the Twentieth Step.

References:

• 97 things Every Programmer Should Know ~ Git Book
• 97 Things Every Programmer Should Know ~ Paperback
• What is API? Medium Blog
• API Design~ Martin Fowler.com
• Google Cloud Api Design Guide ~ Quora
• How to Design A Good Api and why it Matters ~ Joshua Bloch Git
• How to Design A Good Api and Why it Matters ~ Joshu Bloch Video