apidays LIVE LONDON - Exploring an API with Blocks by Larry Kluger
0 likes47 views
The document outlines the features and development of an API request builder tool designed to simplify the process of making API calls through a user-friendly interface. It integrates functionalities such as auto-generating SDKs, supporting deeply nested attributes, and providing pre-built examples for modification and reuse. The preliminary feedback from customers has been positive, indicating its effectiveness as a developer resource, with plans for a confidential release in December and an open-source version available now.
apidays LIVE LONDON - Exploring an API with Blocks by Larry Kluger
- 2. 2 API Request Builder Exploring APIs with blocks Larry Kluger Lead Developer Advocate Larry.Kluger@docusign.com @larrykluger linkedin.com/in/larrykluger
- 3. 4 What’s an API Explorer? A tool for making live calls to the API endpoints. AKA, “API Playground” Make it easy to try your API API Explorers developer.dailymotion.com/tools/
- 4. 5 • Zero to hero: quickly try the API without writing a program or script. • Best: typed requests enable Select boxes, numeric entry, checkboxes, etc API Explorers: Benefits developer.dailymotion.com/tools/
- 5. 6 Some API Explorers use a text area for creating the request. Benefits: easily save and reuse the request; easily support nested objects Issue: more thinking is required; easier to make an error; the explorer is no longer click & go Text areas for the request docs.adyen.com/api-explorer
- 6. 7 Issue: text format has no guardrails—you’re programming, not exploring Six levels of nesting, and this is not a complicated request Nested objects in the API requests
- 7. 8 An API explorer that supports: • Click & go, easy request creation • Supports deeply nested API attributes (arrays and objects) Goal #1
- 8. 9 • Include API documentation • Show the request as JSON • Auto-program the request using an SDK in multiple languages • Load pre-built examples and then modify them • Save your work for re-use • Share your examples to help others Additional feature requests
- 9. 10 Demo
- 10. 11 An API explorer that supports: • Click & go, easy request creation • Supports deeply nested API elements (arrays and objects) Solution step 1 • Use the open source Google Blockly library developers.google.com/blockly Solving Goal #1
- 11. 12 Solution step 2 • Use the builder pattern to add data to the request object • Order counts! Each block affects the nearest prior appropriate object Solving Goal #1
- 12. 13 Solution step 3 • The blocks create a fluent (or chained) output program. Solving Goal #1 new docusign.EnvelopePlusJSON() .add_envDefAttribute("emailSubject", "Please sign the attached document") .add_envDefAttribute("status", "sent") .add_object("document", { filename: "anchorfields.pdf", name: "Example document", fileExtension: "pdf", documentId: "1" }) .add_object("signer", { email: "signer_email@example.com", name: "Signer's name", recipientId: "1", clientUserId: "1000" }) .add_object("signHere", { anchorString: "/sig1/", anchorXOffset: "20", anchorUnits: "pixels" }) .add_object("recipientViewRequest", { returnUrl: "http://localhost:3000/", authenticationMethod: "none", clientUserId: "1000", email: "signer_email@example.com", userName: "Signer's name" })
- 13. 14 Solving Goal #1 new docusign.EnvelopePlusJSON() .add_envDefAttribute("emailSubject", "Please sign the attached document") .add_envDefAttribute("status", "sent") .add_object("document", { filename: "anchorfields.pdf", name: "Example document", fileExtension: "pdf", documentId: "1" }) .add_object("signer", { email: "signer_email@example.com", name: "Signer's name", recipientId: "1", clientUserId: "1000" }) .add_object("signHere", { anchorString: "/sig1/", anchorXOffset: "20", anchorUnits: "pixels" }) .add_object("recipientViewRequest", { returnUrl: "http://localhost:3000/", authenticationMethod: "none", clientUserId: "1000", email: "signer_email@example.com", userName: "Signer's name" }) Solution step 4 • Software creates the JSON version • (Recursion is fun!)
- 14. 15 The Swagger (OpenAPI Specification) file defines the API’s methods, objects, their attributes, types, and relationships. It includes documentation too. The DocuSign eSignature Swagger file is automatically produced by the platform software itself. The tool is built from the API’s Swagger file
- 15. 16 Auto-programming the API’s SDKs The CodeGen software auto- generates the SDKs from the Swagger file The API Request Builder tool uses recursion to auto-program the SDK from the JSON, starting with the deepest leaf nodes
- 16. 17 Auto-programming the API’s SDKs
- 17. 18 • C# • Java • PHP • Node.js • Visual Basic (no SDK) • Python • Ruby Auto-programming
- 18. 19 ü Include API documentation ü Show the request as JSON ü Auto-program the request using an SDK ü Load pre-built examples and then modify them ü Save your work for re-use ü Share your examples for helping others Additional feature requests
- 19. 20 Preliminary customer developer feedback was positive Internal reviews have also been positive The tool includes an NPS survey and will enable developers to supply feedback Feedback
- 20. 21 CONFIDENTIAL Release planned for December Open source version available now: github.com/docusign/api-request- builder-open-src Status
- 21. 22 Questions?
- 24. 25 Just three methods are needed (per SDK language) • Assign an array of objects to a variable • Assign an array of scalars to a variable • Assign an associative array (aka object or hash) to a variable Auto-programming SDK source
- 25. 26 Building the API Request Builder
- 26. 27 • As a separate batch process, a configuration app parses the Swagger file and creates the block definitions, plus relationship records. The output of the configuration tool is used to build the React tool. • React single page application • DocuSign UX library • No significant server components. The tool makes direct calls to DocuSign via CORS. API Request Builder tool
- 27. 28 • When new documents or diagrams are “uploaded” to the tool, they’re processed within the browser since there is no server. • Likewise, when a diagram file is “downloaded” from the tool, the file is being created within the browser, then downloaded to the desktop. API Request Builder tool
- 28. 29 Demo items Sections of the tool Demo the initial diagram Open an example diagram for checkboxes Show comments Show hover documentation Move blocks around to show error message Undo, re-do Control-Z and SHIFT Control-Z Duplicate blocks Show toolbox Show documents Show video