Api more than payload (2021 Update)
0 likes71 views
Phil Wilkins discusses the essential elements of API design, emphasizing that it's beyond just payload definition and involves addressing security, internal and external usage, and user support. He advocates for the use of SDKs and documentation to facilitate API adoption and provides insights on optimizing internal API gateways. The document serves as a guide for improving API development practices within organizations.
Api more than payload (2021 Update)
- 1. © 2021 – Phil Wilkins – mp3monster.org Phil Wilkins Tech Evangelist & Ace Director Phil.Wilkins@capgemini.com uk.linkedin.com/in/philWilkins @PhilConsultant / @MP3Monster Oracle-integration.cloud / APIPlatform.cloud / Blog.mp3monster.org API Design – More than just a Payload Definition (2021 Edition)
- 2. © 2021 – Phil Wilkins – mp3monster.org The About Me … Me in 6: • Family man, Blogger & Author • Technical Architect, Tech Evangelist • Work for Capgemini UK as part of a multi award winning team • Work with primarily open source + Oracle middleware & cloud • Recognized by Oracle as an Ace Director – domain knowledge & community contribution • Know more – mp3monster.org https://blog.mp3monster.org/ publication-contributions/ https://bit.ly/FluentdBook https://bit.ly/ImplementingAPI https://oracle-integration.cloud
- 3. © 2021 – Phil Wilkins – mp3monster.org Capgemini is One of the World's Largest Consulting, Technology, and Outsourcing Firms & a global “full service” business transformation provider Group Workforce: 200,000+ Globally Asia Pacific Latin America Canada United States Mexico Brazil Argentina Europe Morocco Australia People’s Republic of China India Chile Guatemala Russia Singapore Hong Kong North America UK & Ireland Nordics Benelux “It is the quality of our people, and their capacity to deliver fitting solutions, with you and for you, that drive real business results.” Across 40+ countries, 100 nationalities 5Businesses Revenue 12,8 Billion EUR (2017) Central Europe Morocco Net Profit €1,18B Targeting Value Mitigating Risk Optimising Capabilities Aligning the Organisation Elements to successful collaboration Application Services Infrastructure Services Business Process Outsourcing Consulting (Capgemini Consulting) Local Professional 4
- 4. © 2021 – Phil Wilkins – mp3monster.org APIs, more than a Payload?
- 5. © 2021 – Phil Wilkins – mp3monster.org Thanks to API Handyman (Arnaud Lauret) http://openapi-map.apihandyman.io/ The parts of OAS we focus on when developing an API
- 6. © 2021 – Phil Wilkins – mp3monster.org Thanks to API Handyman (Arnaud Lauret) http://openapi-map.apihandyman.io/ The parts of OAS we focus on when developing an API
- 7. © 2021 – Phil Wilkins – mp3monster.org Thanks to API Handyman (Arnaud Lauret) http://openapi-map.apihandyman.io/ Extending the schema option to convey extra details
- 8. © 2021 – Phil Wilkins – mp3monster.org Thanks to API Handyman (Arnaud Lauret) http://openapi-map.apihandyman.io/ Security controls – not obvious …
- 9. © 2021 – Phil Wilkins – mp3monster.org API Wall for External APIs Authentication & Authorization SDK / Code Generator Test Framework
- 10. © 2021 – Phil Wilkins – mp3monster.org But my API is not for external use!
- 11. © 2021 – Phil Wilkins – mp3monster.org … will you be supporting your API for the rest of your career or it’s lifecycle? What about the impact of an API Gateway on your API use? Internal or External – your API will be looked at by others
- 12. © 2021 – Phil Wilkins – mp3monster.org Internal API Gateways We should be considering internal gateways to … • Enforce rate limiting to avoid possible runway processes swamping you with API calls • Capture usage data for billing • Creating points of abstraction • Gateways can mask changes in deployment for consumers • Enforce loose coupling – some APIs are intended operational purposes NOT for others to build new applications against • Gateway as a focus of security management • Provide easier points for measuring utilization (investment value) These points are not easily defined in an API spec … But can be supported by referenced documentation
- 13. © 2021 – Phil Wilkins – mp3monster.org Supporting Adoption and Change Every time someone wants to use your API internally, do you want to be receiving over Slack, Skype, Teams, email random questions about … • Where do I test my use of your API? • My call keeps failing – why? • How do I get credentials to use your API? • Why can’t I … All these points are not easily answered in an Open API spec • We talk about self service in our everyday lives, many of us even prefer it • Many API Design Tools offer mock endpoints – tell people where it is • Provide examples – so people can see what will work and why • Point to the internal process or service for securing access • You can deliver an SDK to make it easier to use your API faster than anyone else when it comes to coding – you know the API best
- 14. © 2021 – Phil Wilkins – mp3monster.org API Wall for External APIs Authentication & Authorization SDK / Code Generator Test Framework
- 15. © 2021 – Phil Wilkins – mp3monster.org API Wall for Internal APIs Legalese Authentication & Authorization SDK Test Framework
- 16. © 2021 – Phil Wilkins – mp3monster.org Still with me ? Solving the problem … bi-products & benefits
- 17. © 2021 – Phil Wilkins – mp3monster.org What to do ? 1. Create yourself a checklist like our “wall”, decide what “bricks can help” in a situation 1. As an organization agree common ways of providing the ‘bricks’ 2. Use a design tool that provides mock end points & share the links 3. Provide additional docs .. 1. Answer the sort of questions / points discussed, could be simple as Markdown in your repository 2. Incorporate the doc reference into the API Spec 3. More accessible the supporting content – the better 4. Try to avoid burying answers in big docs 4. Think about what you’d want when trying to use an API, and what if it doesn’t go right 5. If you get asked for the same thing more than a couple of times – address it, own it rather than problems own you (better than the continued interruptions, debates about accountability)
- 18. © 2021 – Phil Wilkins – mp3monster.org Feedback Design Build Package & Deploy Try Continuous Test Feedback Run Analyse Feedback Build Package & Deploy Try Continuous Test API Provider API Consumer API 1st – will help identify what is important and requires most support / information Explanation to API first: https://apievangelist.com/2020/03/09/what-is-api-first/
- 19. © 2021 – Phil Wilkins – mp3monster.org Being the next Elon Musk Not all of us, have the benefit of working on APIs for those poster children of the API Economy, But … APIs done right can… • See opportunities to expand on current services – offer the same service in different ways – Walgreens photo printing, PSD2 Banking (new user experiences) • People can see the ‘art of the possible’ with your API and realize new solutions etc Cloud Elements 2021 State of APIs report https://offers.cloud-elements.com/2021-state-of-api-integration-report
- 20. © 2021 – Phil Wilkins – mp3monster.org State of API Report 2021
- 21. © 2021 – Phil Wilkins – mp3monster.org Better handle & communication on how your API will evolve and version
- 22. © 2021 – Phil Wilkins – mp3monster.org Not be the cause of a security issue (or better be the person who helped prevent one) A1:2019- Broken Object Level Authorization A2:2017- Broken Authentication A3:2019- Excessive Data Exposure A4:2019 - Lack of Resources & Rate Limiting A5:2019- Broken Function Level Authorization A6:2019- Mass Assignment A7:2019 - Security Misconfiguration A8:2019 - Injection A10:2019- Insufficient Logging & Monitoring A9:2019- Improper Assets Management
- 23. © 2021 – Phil Wilkins – mp3monster.org Providing an SDK Sometimes an SDK may ease adoption for the common ways of using an API… • Your API may use an approach less commonly used e.g. BSON, gRPC etc – why increase the learning curve, provide an SDK that makes it easy • Opportunity to incorporate additional metadata about the use of the API, by allowing the SDK to capture additional information • If your API needs metadata to describe the content being communicated, the SDK can determine this for the consumer • If you’re APIs have been defined using one of the lesser known notations e.g. YAML, an SDK can reduce this as a possible barrier • Making it easier to use your API, particularly for devices & mobile platforms .. • Coding against a SDK means development or compile time we’re more likely to spot usage errors (class mismatches etc etc) • Using dependent libraries is something every developer learns very early on There are tools that can make this process a lot simpler e.g. • APIMatic • APITools • RESTUnited • Swagger CodeGen • AutoRest
- 24. Illustration of beyond the payload
- 25. © 2021 – Phil Wilkins – mp3monster.org Look at Google Maps … as an example of Good API Provide both APIs and SDKs to make adoption easy
- 26. © 2021 – Phil Wilkins – mp3monster.org Understanding the consuming audience Giving the bigger picture
- 27. © 2021 – Phil Wilkins – mp3monster.org Explanation on how the API use is paid for and requirements to use the API Enabling self service
- 28. © 2021 – Phil Wilkins – mp3monster.org
- 29. With more than 190,000 people, Capgemini is present in over 40 countries and celebrates its 50th Anniversary year in 2018. A global leader in consulting, technology and outsourcing services, the Group reported 2016 global revenues of EUR 12.5 billion. Together with its clients, Capgemini creates and delivers business, technology and digital solutions that fit their needs, enabling them to achieve innovation and competitiveness. A deeply multicultural organization, Capgemini has developed its own way of working, the Collaborative Business Experience™, and draws on Rightshore®, its worldwide delivery model. About Capgemini Learn more about us at www.capgemini.com This message contains information that may be privileged or confidential and is the property of the Capgemini Group. Copyright © 2018 Capgemini. All rights reserved. Rightshore® is a trademark belonging to Capgemini. This message is intended only for the person to whom it is addressed. If you are not the intended recipient, you are not authorized to read, print, retain, copy, disseminate, distribute, or use this message or any part thereof. If you receive this message in error, please notify the sender immediately and delete all copies of this message.
Editor's Notes
- #7: Who uses the external docs attribute that exists in each of the HTTP verbs? Terms of ~Service in the info block ? Did you know that security is at the API route and linked to each path’s verbs? How often do you see the use of the x- property? https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/ghes-2.22/ghes-2.22.yaml
- #9: Terms of Service – its just a URL. Recognition you might to provide this – but it points us out of the API definition
- #12: - A simpler view like this simpler prompt - Have the chance of a good external API, we need address these bricks – miss breaks, less likely to succeed
- #15: API gateways don’t have to be
- #17: Have the chance of a good external API, we need address these bricks – miss breaks, less likely to succeed
- #21: The API 1st design process likely to draw out the non payload questions e.G internal API using Oauth against corporate IDAM solution – nothing more needed. But delegated Asuth to partners’ IDAM – that needs a lot more detail
- #23: Clips from - APIs Arent Just for Tech Companies – HBR - https://hbr.org/2021/04/apis-arent-just-for-tech-companies - API management, now a business-critical capability – IT Pro Portal - https://www.itproportal.com/features/api-management-now-a-business-critical-capability/ How API economy is powering digital transformation – Venture Beat - https://venturebeat.com/2021/05/17/how-the-api-economy-is-powering-digital-transformation/#:~:text=%E2%80%9CAPIs%20allow%20businesses%20to%20more,retention%2C%E2%80%9D%20Polyakov%20told%20VentureBeat. 2020 Study: 83% find API Integration ‘Critical’ to Business Strategy – Globe Newswire - https://www.globenewswire.com/news-release/2020/04/14/2015763/0/en/2020-Study-83-find-API-Integration-Critical-to-Business-Strategy.html The seven make-or-break API challenges CIOs need to address – McKinsey Digital - https://www.mckinsey.com/business-functions/mckinsey-digital/our-insights/the-seven-make-or-break-api-challenges-cios-need-to-address 90 percent of executives say ‘APIs are mission critical’: What CEOs should know – Health Evolution - https://www.healthevolution.com/insider/90-percent-of-executives-say-apis-are-mission-critical-what-ceos-should-know/ Why have Open APIs become business critical to the CSPs future? - https://www.neuralt.com/wp-content/uploads/2021/01/Open-API-Critical-to-Future-of-CSPs-1.pdf
- #25: By versioning we can manage change. But how to version? If you were to ask Roy Fielding, ‘father’ of REST, he may tell you not to version your API at all Semantic Versioning (semver.org) ? What ever answer you choose, be consistent, be clear & be understood!! Common options … URL & Domain Versioning Query Parameter use Header Attribute Accepts Header Attribute Versioning the Payload Non-breaking evolution
- #26: - None of these issues are directly linked to the payload design. - The issues are linked those things we setup around our API - Thinking bigger than payload reminds up to address these factors
- #27: Developing the SDK can save others time. Helps you with ensuring your API is easy to consume