apidays LIVE New York 2021 - Docs Driven API Development by Rahul Dighe, Paypal
Download as PPT, PDF0 likes122 views
This document discusses an approach called "docs driven development" (DDD) where documentation is written before code is developed. The key points are: DDD involves writing low-fidelity documentation like integration guides and API specifications before writing code. This helps align teams, get early feedback, and remind developers what product they are building. Potential benefits include fewer gaps in products and better alignment between teams. DDD is not a replacement for formal documentation or testing, but is meant to guide development from the start. The document provides examples of how DDD can be implemented and addresses common concerns about the approach.
apidays LIVE New York 2021 - Docs Driven API Development by Rahul Dighe, Paypal
- 1. DOCS DRIVEN DEVELOPMENT RAHUL DIGHE LEAD PRODUCT APIS @ PAYPAL / BRAINTREE @RAHULDIGHE | [email protected] I ❤️ API’S
- 2. ETERNAL DEBATE CODE FIRST OR DESIGN FIRST https://swagger.io/blog/api-design/design-first-or-code-first-api-development/ Design + Code IN PRACTICE 2
- 3. DOCS DRIVEN DEVELOPMENT WHAT IS IT Write the Docs ‣ Integration Guide / User Manual / User Guides (low fidelity) ‣ As viewed by the end user (aka developer) ‣ End Points / Nomenclature ‣ Define Open API specs ‣ Code ‣ Docs the Code via Integration guides, API references et.al 3
- 4. DOCS DRIVEN DEVELOPMENT POTENTIAL BENEFITS ▸Continuous reminder of what product you are building and for whom. ▸A more holistic e2e view of integration that typically involve multiple steps using 1 or more developer products (APIs / SDKs). ▸Help align disparate teams that otherwise would have worked in silos. ▸Facilitates thinking and conversation about architecture and design upfront. ▸Aids competitive analysis. ▸Allows for feedback before even a piece of code is written. ▸Could be initiated by non-engineers as the barrier to entry is low. 4
- 5. DOCS DRIVEN DEVELOPMENT WHAT IT IS (NOT) ▸It is not a replacement to write more formal integration guides prior to launch. ▸It isn’t about writing more comments in your code. ▸It isn’t about working with your documentation team as you are writing code. ▸It isn’t a substitute for Test driven development or Acceptance Test Driven development or Behavior Test driven development et.al ▸It isn’t exactly Readme driven development, although Readme driven development is a subset of it.1 1. https://tom.preston-werner.com/2010/08/23/readme-driven-development.html 5
- 6. DOCS DRIVEN DEVELOPMENT SIGNS THAT IT’S TIME FOR YOU TO TRY DDD ▸ You discover gaps in your products when you write the Integration Guides when everything is “built”. ▸ Every team builds their own APIs / SDKs in “silos”. ▸ Customers complain that products don’t seem to be built by the same company. ▸ You are hiring too many Professional services / Integration engineers to support products. ▸ You have tried Spec first, Code next but it’s not paying dividends. ▸ You notice that after everything is built and documented, the solution is worse off than the competition. © Rahul Dighe “A PERFECT IMPLEMEN TATION OF THE WRONG SPECIFICA TION IS 1. https://tom.preston-werner.com/2010/08/23/readme-driven-development.html Tom Preston-Werner1 6
- 7. A TYPICAL API PRODUCT PROCESS DEPLOY & LAUNCH Sandbox availability User testing Integration Guides GTM activities Setup Monitoring Limited Release DISCOVERY Problem Competitors Customer research Persona Business Case Epics DESIGN Docs Driven Dev End Points / Fields Mocks Frontend tools Specification User Stories DEVELOP Prioritized backlog Spec to Code Security SDK Automated Tests MVP 7
- 8. DEVELOPERS AS CUSTOMERS IT STARTS WITH EMBRACING THE IDEA OF: 8
- 9. BUILD A DEVELOPER PERSONA DEVELOPERS AS CUSTOMERS 9
- 10. DOCS DRIVEN DEVELOPMENT A TYPICAL TEMPLATE ▸ Goal/Use Case - Accept payment using PayPal ▸ Assumptions - Developer has signed up. ▸ Integration Steps ▸Step 1 - Fetch access token ▸ Description ▸ Code Snippet ▸Step 2 - Display PayPal button ▸ Description ▸ Code Snippet ▸… 10
- 11. DOCS DRIVEN DEVELOPMENT DIFFERENCE @ Design / Discovery @ Launch Goal Working backwards, Competitive analysis, Feedback Aid to developers integrating with your product Fidelity Low High API Specs End Points / Key Fields Complete Open API Spec Overview Not needed Generally included Sequence diagrams Not needed Generally included Code Snippets Yes Yes Use Case Key Use Case As needed Persona Key Developer Persona Key Developer Persona 11
- 12. “HOW CAN YOU DOCUMENT ANYTHING BEFORE IT’S BUILT THE SKEPTICS, NAYSAYERS, DEVIL’S ADVOCATES… DOC FIRST DEVELOPMENT “DID YOU NOT SAY YOU WANTED THE API BUILT YESTERDAY? “I’M NOT A GOOD WRITER “NO ONE ON MY TEAM LIKES/WANTS TO DOCUMENT “I DON’T SEE HOW THIS IS FASTER THAN JUST WRITING CODE 12
Editor's Notes
- #2: Hello everyone - My name is Rahul Dighe and I currently lead API products at PayPal. Today I am going to talk about 3 main things > Make a case to think of APIs as products? > How do you take the first steps in thinking of APIs as products? > How do you embed API-as-a-Product culture within your company? But most importantly, I just want you to take back with you and get excited about APIs. With that let’s dive in.
- #9: Think about your offerings - what would a product that would have the developer as a customer look like ?