This document discusses principles for effective API design. It defines an API as providing a way for developers to interact with and consume a service. It outlines six principles for API design: design first, choose the right runtime, define contracts, monitor usage, continuously improve, and socialize APIs. The principles emphasize designing for developers and specific use cases, ensuring scalability and reliability of the runtime, and engaging with developers through documentation and community. Well-designed APIs that follow these principles can become valuable products and ecosystems, while mediocre APIs that don't engage stakeholders may fail to meet business objectives.

1. Effective API Design
Bansi Haudakari

2. API’s Are
For the Developers,
By The Developers
And
Of the Developers
- Bansi Haudakari

3. Who Am I?
• An API Developer
• An API Consumer
• An API Designer
• A Seasoned JAVA Programmer
who has been consuming JAVA
API’s since JDK 1.0 And Other
Open Source APIs For Software
Development

4. Agenda
• What is an API?
• Driving factors Of an API
• Principles of Effective API Design
• Value Of Great APIs
• Pitfalls of mediocre APIs
• Craft APIs that Developers Love

5. What is an API?
Application Programming Interface provides a
way for developers to interact with and consume a
service.

6. Analogy: Electrical Sockets
• APIs are gateways between Services and Consumers, providing
consumers access to services through various interfaces
Example: Service : Electricity AND Consumer : Plug
• Our laptops, consumes electricity through a socket. Through its own
“API,” a USB socket, it can provide that same electricity service to
charge other devices.

7. Driving Factors
• Business Agility : Business Logic is exposed thru
APIs thereby enabling customers to focus on
innovations
• API Economy : Businesses are developing “API
products” as new sources of revenue. Expedia
generates over $2 billion thru data made
available through their API
• Internet of things: The number of things that
can be connected is growing fast; everything
from your coffee pot to your thermostat to
your car can now be accessed thru APIs

8. Principle 1 : Design First API
• With Design-First approach, focus is on
well-defined API spec’s instead of
implementation concerns.

9. • With an Design-First API approach, rather
than implementing an application and then
building API on top of it, first create the
interface and then put the back-end logic
into place - whether it be cloud-based or
on-premise.
• An optimal API design enables applications
developers to easily understand the
purpose and functionality of the API.
• It also allows organizations to focus on
getting API design right before investing in
back-end implementation,

10. • The best way to design an API that developers
want to use is to iteratively define the
structure of the API in an expressive manner
and get feedback from developers on its
usability and functionality
• As the API is designed, application developers
can interact with it and test its behavior,
thanks to an integrated mocking service that
returns the values a call to the live API would
produce.

11. • There is no such thing as a one-size-fits-all API
• An API should be optimized to fulfill a specific
business request in a specific context.
• Optimize API for a specific use case e.g.
– coarse or fine-grained
– constraints e.g. network trips, latency and data
size so API should be designed to limit backend
calls and minimize the size of data returned

12. Principle 2 – Runtime API
• Once an API is designed, created and its back-end
implemented, it’s time to find the right
run-time as it affects How successful your API
strategy will be in terms of service, liability,
scale and ability to meet future needs.
• Hybrid support: As more and more businesses
are moving to the cloud, so it is important to
find runtime that allows to deploy applications
both in the cloud as well as on-premise without
having to modify anything.

13. • Scalability, reliability, availability: These “-ilities”,
along with performance, are crucial when
searching for a solid API runtime. The last thing
you want is an unstable runtime that crashes or
experiences outages. Choosing the right
enterprise grade technology for your API runtime
is crucial to the success of your API.
• Strong Orchestration: A successful runtime should
provide strong orchestration and orchestration
capabilities. The ability to carry out complex back-end
orchestration plays a key role in translation
between the API layer and back-end
implementation.

14. Principle 3 – API Design Contract
• API publishers should offer a way to easily
create well-defined policies and contracts and
associate them with the right APIs and
consumers.
• API Contracts are crucial for enforcing security
and managing SLAs with API consumers.
• In addition, publish API version which helps in
lifecycle management and allows API publishers
to assess the impact of retiring a version.
Example REST API’s

15. Principle 4 - Monitor API Usage
• The ability to monitor API usage over a period of
time and understand usage patterns from both
technical and business perspectives is valuable as
it helps business owners and technical teams
better understand their users and ultimately
create a better service.
• You need to see how consumers are using it i.e.
which parts of your service are being used.
• With metrics for both overall usage and per
consumer usage, businesses can closely monitor
API activity and engagement.

16. Principle 5 - Continuous Improvement
• The ability to re-factor your APIs by iterating
through habits 1-6 multiple times allows you to
optimize your API over time to improve
consumer experience and productivity.
• API is not a static entity – as new use cases are
identified and use of your API expands,
enhancements and fixes are inevitable.

17. Principle 6 -Socialize Your APIs
• Create a developer portal to establish a
community around your API is important to its
success. By making it easy for users to follow
your API, download documentation and ask
questions, API publishers can engage with API
consumers on an ongoing basis.
• Example create a developer portal for company-wide
REST services and document it using
Swagger

18. • APIs delivers an end-to-end solution to design
APIs that developers will love; easily connect
them with backend services; run them in a
secure, scalable environment; and manage
them throughout their lifecycle.

19. APIs Are Everywhere

20. Value of Great API’s
• Is a Product
• Help Grow a Eco-System of employees, customers
and Partners
• Evolve in a way that are mutually beneficial
• Encourage Adoption
• Ease Of Use
• Great APIs aren’t difficult to develop
– if you design for your users and the business processes
– if you make it easy for developers to find and consume
your API, and
– you actively manage your API developer community as
an extension of your business.

21. Pitfalls of a mediocre APIs
• Doesn’t engage Stake-holders
• limited adoption by developers and ultimately, a
failure to meet business objectives
• Starts with implementation first
• Design of API is dictated by the constraints of
internal systems or processes.
• Too often APIs are modeled after the design of the
backend services or applications they expose
instead of the use case they fulfill. This results in
poor performance of the client application, poor
user experience, and ultimately, poor adoption.