The document discusses the development of an API request builder tool that allows users to visually construct API requests using blocks. It describes how the tool uses the Google Blockly library and recursion to build requests and auto-generate code in multiple programming languages from an API's OpenAPI specification file. The tool addresses goals like easy request creation for nested objects, including documentation, viewing requests as JSON, and auto-programming SDKs. An early version received positive feedback, and a public release is planned for the summer.

1. 6/11/20
1
1
2
API Request Builder
Exploring APIs with blocks
Larry Kluger
Lead Developer Evangelist
Larry.Kluger@docusign.com
@larrykluger
2

2. 6/11/20
2
4
What’s an API Explorer?
A tool for making live
calls to the API
endpoints.
AKA, “API Playground”
N.B. “API Explorer” is
also used for static API
documentation.
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

3. 6/11/20
3
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

4. 6/11/20
4
8
For APIs with many
nested objects, the
form UX is problematic.
Nested objects in the
API requests
apiexplorer.docusign.com
Four levels
of nesting
8
9
An API explorer that supports:
• Click & go, easy request
creation
• Supports deeply nested API
elements (arrays and objects)
Goal #1
9

5. 6/11/20
5
10
• 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
10
11
Demo
11

6. 6/11/20
6
12
An API explorer that supports:
• Click & go, easy request creation
• Supports deeply nested API
elements (arrays and objects)
Solution step A
• Use the open source Google
Blockly library
developers.google.com/blockly
Solving Goal #1
12
13
Solution step B
• Use the builder pattern to add data
to the request object
• Order counts! Each block affects
the nearest prior appropriate object
Solving Goal #1
13

7. 6/11/20
7
14
Solution step C
• 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"
})
14
15
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 D
• Software
creates the
JSON version
• (Recursion is
fun!)
15

8. 6/11/20
8
16
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
16
17
Demo
17

9. 6/11/20
9
18
• The Builder tool uses
the Swagger file
definitions to
automatically create
arrays as needed
Automatic array creation
"envelopeDefinition": {
"documents": [
{
"filename": "anchorfields.pdf",
"name": "Example document",
"fileExtension": "pdf",
"documentId": "1"
}
]
}
An array was automatically created
for the document object
18
19
• Objects that have no
scalar attributes can
also be automatically
created
• Automatic arrays and
objects simplify the
diagram and the
fluent program
Automatic object creation
"envelopeDefinition": {
"recipients": {
"signers": [
{
"email": "signer_email@example.com",
"name": "Signer's name",
"recipientId": "1",
"clientUserId": "1000"
}
]
}
}
The recipients object was
created automatically
An array was also created
for the signer object
19

10. 6/11/20
10
20
Auto-programming the API’s SDKs
The CodeGen software auto-
generates the SDKs from the
Swagger file
The Builder tool uses recursion
to auto-program the SDK from
the JSON, starting with the
deepest leaf nodes
20
21
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
21

11. 6/11/20
11
22
Auto-programming the API’s SDKs
22
23
Today
• C#
• Java
• PHP
• Node.js
• Visual Basic (no SDK)
Auto-programming
Planned
• Python
• Ruby
• Curl
• Powershell
• And more
23

12. 6/11/20
12
24
ü 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
24
25
Building the API Request Builder
25

13. 6/11/20
13
26
• 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
26
27
• 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
27

14. 6/11/20
14
28
Preliminary customer feedback was
positive
Internal reviews have also been
positive
The tool includes an NPS survey and
will enable developers to supply
feedback
Feedback
28
29 CONFIDENTIAL
First public release planned for
Summer
Open source version is planned
for next year
Status
29

15. 6/11/20
15
Thank YouThank You
Larry.Kluger@docusign.com
@larrykluger
31
32