INTERFACE by apidays 2023 APIs for a “Smart” economy. Embedding AI to deliver Smart APIs and turn into an exponential organization June 28 & 29, 2023 Designing APIs That Stand the Test of Time Pooja Mistry, Developer Advocate at Postman ------ Check out our conferences at https://www.apidays.global/ Do you want to sponsor or talk at one of our conferences? https://apidays.typeform.com/to/ILJeAaV8 Learn more on APIscene, the global media made by the community for the community: https://www.apiscene.io Explore the API ecosystem with the API Landscape: https://apilandscape.apiscene.io/

1. All rights reserved by Postman Inc
Designing APIs that
stand the test of Time
Pooja Mistry
Developer Advocate
@poojamakes

3. Hi, I’m Pooja!
@poojamakes
Developer Advocate, Postman
Postman is an API platform for building and using APIs. It
is used by 25 million + people world wide 🌏🌎🌍
For many teams, Postman is an everyday tool that helps
people work with APIs more efficiently
@poojamakes

4. We are moving
towards an
API First World
@poojamakes

5. Code-First Development
CORE
FUNCTIONALITY
API web app
admin app
mobile app
microservice
API
@poojamakes

6. @poojamakes

7. API-First Development
API web app
admin app
mobile app
@poojamakes

8. ● It’s a model of software development
in which applications are conceptualized and built as an
interconnection of internal and external services through
APIs. APIs are prioritized over applications.
● It’s an organization mindset
API-First organizations include APIs in their strategy,
thinking their operations through added-value APIs hiding
complexity.
● It’s for all types of organizations and
APIs
Becoming API-First isn’t reserved to startups, silicon valley
companies, or organizations providing public facing APIs.
What API-First is
@poojamakes

9. 8 traits of an effective API-first design
What problem is your API trying to solve?
@poojamakes

10. The Impact of the API Experience
Good API experience
● Usability & Reusability
● Time to value
● Create APIs will evolve smoothly
● Less risk of introducing breaking change
Bad API experience
● Costly
● Decreased Productivity both Consumer &
Producer
● Takes longer time for integration
● Leads to shift delivery dates
@poojamakes

11. Better Practices and Usual Concerns for Good API Design
● Naming
● Data Modeling
● Required/ Not Required
● Error handling
● Documentation
● Consistency
@poojamakes

12. The OpenAPI Specification:
A machine-readable and human-friendly API description format
● Describes REST(ish) web APIs
● Uses JSON Schema to describe data
● Written in JSON or YAML
● Vendor neutral, technology agnostic
and Interoperable standard
@poojamakes

13. Let’s Brew Some Coffee
@poojamakes
Always analyze the needs/the problem you
want to solve using natural language before
choosing between GET /this and POST
/that. It will help you decide which
operations are needed in the API.

14. Let’s Brew Some Coffee
@poojamakes

15. Better Practices and Usual Concerns for Good API Design
● Naming
● Data Modeling
● Required/ Not Required
● Error handling
● Documentation
● Consistency
@poojamakes

16. Naming
Naming Is hard
Rule of thumb: should be
consistent at every level
● endpoint names
● method names
● response codes.
@poojamakes

17. Data Modeling
Without proper data typing, there could be errors or misinterpretation of data, resulting in incorrect
output or unintended consequences.
@poojamakes

18. Required or Not Required
@poojamakes
● Required parameters : are
those that must be included in
an API request to receive a
valid response. - They are
essential for ensuring that the
API can process the request
and provide accurate data.
● Not-required parameters:
are optional and are not
necessary for the API to
function correctly. They can
provide additional information
that may enhance the
response or help to customize
the output.

19. Error Handling
@poojamakes

20. Error Handling
@poojamakes

21. Thank you
@poojamakes
@poojamakes