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 API Design Governance - Key to building consistent APIs at scale Nauman Ali, Product Manager at Stoplight ------ 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. API Design
Governance
Key to Desigining APIs at Scale
Nauman Ali, Product Manager at Stoplight

3. 2
Fragmented and
Inconsistent APIs:
The Silent Saboteurs of
Scaling Digital Enterprises
Across Industries

4. 3
API Governance:
Paving the Road from
Fragmentation to
Streamlined Synergy

5. 4
Key Objectives
Consistency: Ensuring uniformity in API design across our
digital ecosystem.
Interoperability: Facilitating seamless interaction of APIs
with various systems.
Collaboration: Encouraging cross-team collaboration for API
development.
Security: Protecting our APIs from potential vulnerabilities.

6. 5
Getting Started with
API Governance

7. 6
Essential Tips for the Governance
Journey
Start and Grow: Think of API governance like a road
trip. Start your journey now and keep learning and
improving along the way.
Make It Easy: The best way to do API governance?
Make the right way the easiest way. Simplify the
process and people will follow it.
Automate: Let machines do the work! Use automation
wherever you can.

8. 7
Step 1: Make your
APIs Discoverable

9. 8
How: Set up an
API Catalog

10. 9
Mandate writing
having an API
specification

11. 10
Creating an API Catalog: Best Practices
Includes all your APIs: Your API catalog should be a one-stop
shop, featuring every API across the company.
Accessible to Everyone: Ensure your API catalog is universally
accessible within the organization, fostering transparency and
collaboration.
Efficient Search: Incorporate search functionality to swiftly
locate desired APIs, encouraging reuse.
Generated from API specifications: The content of the catalog
should be powered by API specifications. Automate ;)

12. 11
Step 2: Set up
Standards

13. 12
How: Set up an
API Style Guide

14. 13
● Fast reviews
● Scales well
● Great visibility
● Reduced time to market as
team becomes a bottleneck
● Feedback is late in the process
pushing people towards
bypassing the system
API Governance Strategies
Manual Governance
A central API governance team that
reviews all API changes, including
naming conventions.
Automated Governance
Automated set of API standards
helping API governance team.

15. 14
Automation is
the key to effective
API governance.

16. 15
Not the 80-page PDF kind!

17. 16
The automated kind 😉

18. 17
What should an
API style guide include?

19. 18
OpenAPI / AsyncAPI
Best Practices
● Don’t use OpenAPI 2.0
● Add tags to each endpoint and
tags should be defined globally
● Always have an OpenAPI
or AsyncAPI version
● Operation ID should always be
defined and unique
● Add contact / license information
to API documents

20. 19
API URL Guidelines
Host
● Must be lowercase
● Must not have a trailing slash
● Host must follow a structure
→ There are multiple conventions that
organizations follow to structure their
hosts. Some organizations might use
*{domain}/api* while others might go
for an *api.{name}.com* structure.
Paths
● Must be kebab-case
● Don’t use file extensions in Paths
● Don’t add HTTP methods to paths
● Avoid Special Characters
● Use Nouns for Resource Names
Parameters
● Must be kebab-case
● Don’t use file extensions in Paths
api.domain.com Used by:
domain.com/api Used by:
domainapis.com Used by:
underscore_case Used by:
cameCase Used by:
PascalCase Used by:

21. 20
Versioning Strategy
● Must follow versioning strategy
→ There can be multiple versioning strategies for APIs.
Some organizations might use URL versioning while
others might go for path-level versioning.
domain/{version}/products Used by:
/products/{version} Used by:
Version in header Used by:
Version in query Used by:

22. 21
Security Best Practices
HTTPs
● Must use HTTPs
Secure your API with a security scheme
● Must use {OAuth2/OpenID e.t.c}
● Define security globally or on operation level
(i.e. POST/PUT/PATCH/DELETE)
● Always have a 401 defined
Don’t use unsafe schemes
● Use known security schemes
● Don't use HTTP basic / Bearer token / OAuth1
● API key in header/cookie/query isn’t a good idea
Open-ended parameters can be exploited
● Limit array size and numbers i.e. min/max items
● String should have a limit and pattern
● Disable additional properties or constraint them
using min/max properties
OAuth2 Best Practices
● Must use https on oauth endpoints
● Avoid using implicit and password grants
● Always have scopes defined
Rate limiting
● Always include rate limiting headers

23. 22
Error Handling
● Error response must follow a particular structure
● Always include popular error responses
● Enforce error object type
● Must use problem JSON
● No errors in 2xx!
Documentation Guide
● Examples on Payloads (Requests/Responses)
● Enforce descriptions
● Description length
● Always end with a full stop
● Start with a capital letter
● Grammar/Spelling check

24. 23
Tooling Setup
Gateway Setup
● Include x-extensions for gateways; e.g. All
operations must have an x-amazon-apigateway-
integration or service tier information
● Gateway specific limitations; e.g. OneOf is not
supported by Amazon API Gateway
Codegeneration Setup
● Include x-extensions for codegenerators; e.g. All
enums must have x-enum-descriptions e.t.c
Industry Standards
● JSON:API
● Zalando Restful Guidelines
● FHIR
● Open Banking
● IATA
● OWASP top 10

25. 24
Provide Reusable
Components

26. 25
What should the reusable components include?
● Domain models
● Error models
● Pagination models
● Common data types
● Metadata objects
● Enumerations
● Standard Model for Standards like JSON:API

27. 26
Some Public Style Guides to Get Started
● Enforce Https: https://apistylebook.stoplight.io/docs/enforce-https
● OWASP Top 10: https://apistylebook.stoplight.io/docs/owasp-top-10
● URL Guidelines: https://apistylebook.stoplight.io/docs/url-guidelines
● Spell Check: https://apistylebook.stoplight.io/docs/spell-check
● JSON:API: https://apistylebook.stoplight.io/docs/json-api
● Zalando: https://apistylebook.stoplight.io/docs/zalando-restful-api-guidelines
● AWS Gateway: https://github.com/andylockran/spectral-aws-apigateway-ruleset

28. 27
Rolling Out
Standards

29. 28
Socialize the style guide and reusable components
within your organization.

30. 29
Bring it where your designers/developers are.

31. 30
Step 3: Setup a
Review Process

32. 31
Encourage the Git workflow for
a review process.

33. 32
Make standards part of your review process.
GitHub Circle CI
Providing a style guide gets you 80% there. Enforce these rules as part of your
CI in the review process to ensure guidelines are being followed.

34. 33
What should reviews include?
The reviews can now focus on:
● Business Capabilities
● Use Cases
● Developer Experience
API Style Guidelines can take care of
the rest. No long conversations about
naming conventions 😉

35. 34
Improve and Iterate

36. 35
Improved Diffs and Breaking Change Detection

37. 36
Templates with best practices and commonly
used patterns in to kick-start the design process
Templates
Use automatic validation to validate API specifications
against the developed APIs
Validation of API specifications

38. 37
API Governance is a Journey: API governance isn't a
one-off task, but a continuous cycle of refinement.
Every Step Counts: Each advancement, regardless
of size, is a valuable achievement in streamlining your
APIs.
Just Begin: Don't wait for all answers; start now and
learn along the way.

39. 38
Q&A