INTERFACE by apidays 2023 - API Design Governance, Nauman Ali, Stoplight

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/

Transcript

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