apidays LIVE LONDON - The Road to Embedded Finance, Banking and Insurance with APIs API Reques Builder - Exploring an API with Blocks Larry Kluger, Lead Developer Advocate at DocuSign

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?

22. Thank YouThank You
Larry.Kluger@docusign.com
@larrykluger

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