Hello.
I'm Larry Kluger, lead developer evangelist at DocuSign.
Today I'll be talking about Builder Tool, a new style
of API explorer that we're working on for the DocuSign
developer center.
OK.
What's an API explorer?
In this slide, I'm showing a screenshot of a typical API
explorer from Daily Motion.
It enables you to try out their API
for listing videos on their site.
In short, an API explorer or API playground
enables you to try a company's API from the browser
without writing any software or scripts.
Note that some developer portals refer to their API reference
documentation website as an API explorer.
The primary benefit of an API explorer
is that it enables you, the dev portal visitor,
to quickly try out the company's API.
The best API explorers include typed forms
with select boxes, checkboxes, and similar user experience
features to help you create correct API requests.
This API explorer also includes short form documentation
with links to more extensive documentation.
Some API explorers use a text area
for creating the API request.
This has pros and cons.
Benefits include the ability to easily save and reuse
the request body, also an API request
object that includes nested arrays,
and objects can be handled reasonably
well with this format.
But there are downsides.
Other than an initial request skeleton,
any additional request to raise objects or attributes
must be carefully and correctly typed into the text area
by the user.
It's no longer configuration-via-clicks type
of tool.
Here's a JSON request for the DocuSign eSignature REST API.
As a block of JSON code, it has no guardrails.
It's easy to miss a brace or bracket
or to misspell an attribute name.
And you'll notice the six levels of objects and arrays
for even relatively simple requests like this one.
In general, if the API includes many nested arrays or objects,
using a form to describe the request
object can become problematic
this screenshot shows DocuSign's current API explorer,
which uses forms.
Note the presence of the additional rows of the tab
types, which are there in case the developer wants to include
them in the request but which occupy screen real estate even
when not used.
Also the four levels of nesting needed for
even a relatively simple request.
Overall, this API explorer does a good job,
but I want to see if I can develop a new paradigm.
So goal number one is to create an API explorer that
offers click configuration while at the same time cleanly
supporting an API that uses deeply nested arrays
and objects.
I also wanted some additional features in the tool,
include access to the API documentation,
show the completed request as JSON,
auto program the request using SDK languages such as C#, Java,
and so forth, load pre-built examples and then enable
the developer to modify them to meet more specific needs,
ability to save your work for reuse,
and share your examples to help others.
This is an important feature.
The idea is to build an equivalent
of JSFiddler and similar tools.
They enable a developer to easily respond
to a Stack Overflow question, for example,
with an answer that can be immediately tried out
by the reader.
My idea is that the new tool should enable our customer
service developer support engineers and other developers
to easily share solutions for using the DocuSign APIs.
That all sounds good.
Let's see a demo.
Here's a current version of the builder tool.
On the far left is the Block Tool Box,
you'll see it in action shortly.
Next is the current diagram and its workspace,
a set of blocks describing the API request.
The blocks are ordered from top to bottom.
The smaller blocks correspond to an individual attribute.
A container block, such as the overall create envelope
container or the document container
represents an API request object.
Containers include one or more attribute blocks.
Containers do not include other containers, instead,
the tool automatically organizes objects
into arrays and other objects as allowed by the API's Swagger
specification.
The primary pane on the right side of the tool
shows the output.
The tool is currently showing the JSON version
of the block diagram.
The output is always alive and is immediately updated
when the diagram is changed.
The small pane above the output pane is a status log.
When the tool starts up, it contains
the diagram you see here.
Now, I'll update the diagram with my name and email address.
You can see that the output is also updated.
Let's send this envelope request.
We need to first log in.
Note the status window updates as the API requests
are made to DocuSign.
The tool communicates directly with the DocuSign
e-signature system by using cores.
There's no intermediate application server.
Now, we're switching over to the signing ceremony
on the DocuSign server.
After signing the envelope, we're
brought back to the Builder tool.
You can see the Sas logging, including the API
responses from DocuSign.
The Builder tool includes short form documentation for each API
object and attribute.
Documentation is shown when you hover over the block.
Blocks have context menus, which provide a set of operations
including block duplication, deletion, and display
of a comment for the block.
Lets duplicate the document block.
We'll switch to using a different example
document called blank.pdf.
We'll also rename the document and we
need to update the document ID to avoid an API error.
Next, let's open the tabs section of the block tool box.
And then pick the date, signs, and tab blocks.
First, we add the containing block for dates signed at tab.
Next we add the page number, x and y position,
and document ID attributes.
Next step is to set their values.
Now, when we send a new envelope,
the result is an envelope with two documents.
The second one, a blank page, contains the date sign tab.
Next let's change the SDK language to Java.
We can see the output window is updated to show
a Java program, including all of the SDK
calls for the current diagram.
When we change the offset for the sign here tab,
the corresponding Java SDK call is also updated.
The tool includes a list of pre-configured example
diagrams.
Examples include instructions.
And DocuSign will add to the examples over time.
Here is the feature similar to the JavaScript Fiddler tool
to load examples from the internet and from local files.
This will enable the developer community
to provide solutions independent to DocuSign.
When a diagram is opened, it can include its own comments
and instructions.
Save to diagrams can include documents
and additional documents can also be loaded into the tool.
Turning back to the Block Tool Box,
the envelopes create call has over 100 objects that
can be used.
The complete set is in the A to Z section of the tool box.
The first sections of the tool box
show the most used object blocks.
Let's add a certified delivery recipient.
You can see that it was also added to the Java source file.
Now we'll use the blocks' context
menu to open the Blocks Comment window.
The comment will be stored with the diagram.
Blocks can also be collapsed to save room
in the diagram workspace.
That's been a short tour of the builder tool.
Now I'll discuss its architecture
and major components.
The most important design goal is
to provide a click-and-go API explorer that supports
deeply nested API elements.
There are several parts to this solution.
Step A was the decision to use the open source Google Blockly
library.
The tool use the stock Blockly library with no changes,
enabling easy updates to new versions of the library.
The library is not hard to use.
The documentation and the React example were very helpful.
Step B was a decision to use the builder pattern for the blocks.
With this pattern, each block is additive.
Therefore, the builder tool user does not
need to worry about arrays, child
objects, grandchild objects, and so forth.
The result is an intuitive arrangement
of blocks to form even the most complicated API request.
The blocks are ordered from top to bottom in the diagram.
Each block affects the nearest prior appropriate object.
Step C. Each block includes a small JavaScript function
that outputs a section of the software.
Altogether, the blocks create a fluent output program.
This software pattern is also called chained methods.
You can see that each method call against the object
returns the object itself.
Step D. An additional layer of software takes the fluent input
and produces the JSON output.
This software uses lookup tables generated from the Swagger file
for the potential relationships between container objects.
Recursion is fun.
The Swagger file for the API defines API's methods,
objects, their attributes, types, and relationships.
It includes documentation too.
The DocuSign e-signature Swagger file
is automatically produced by the platform software itself.
DocuSign publishes a Swagger file for the e-signature API.
And we have customers who use it to build
their own customized tools.
Due to the size of the DocuSign e-Signature API
and the included documentation, the Swagger file
weighs in at almost 3 megabytes.
Let's check out some more features of the builder tool.
If a container block is inserted in a wrong place
and one of its possible parents is not present,
then the error message shows the type of parent block
that is needed.
Also, a block is not allowed into a wrong container block.
Note how gray preview locations are only
shown for valid potential destinations
of the block removing.
Now I'll add the email tab block properly along
with its attribute blocks.
Let's test the envelope.
It works.
And we can see the email tab to the right of the signing tab.
Next, we will download the framework for the example.
Here, we're using node.js.
Opening a terminal window, we unzip the file
and use the NPM install command to install
the examples' dependencies including the DocuSign node.js
SDK.
The example framework includes an index.js file,
which tells us to replace that file with the index.js
file from the example from the builder tool.
Going back to the builder tool, we download the example itself,
the index.js file, and the next step
is to edit the index.js file.
We'll change the redirect URL to be the general DocuSign
website.
All done.
Let's run the program.
The program prints the URL for the signing ceremony
from DocuSign on the console.
Next, we'll open an incognito browser window
and open the signing ceremony URL there.
DocuSign opens, and we can see that the envelope was
created correctly, including the email tab.
After we complete the signing ceremony,
we are redirected to the main DocuSign site, as we requested.
Note the event query parameter is
set to signing complete that the signing ceremony gave us.
Back to the builder tool, two more items to demonstrate.
The example code includes the user's account ID
and a current access token.
Including the access token enables
the developer to immediately try out the generated code.
However, for production, the developer
must update their application to use one of DocuSign's
OAuth authentication flows.
Automatic arrays and objects.
We'll first remove all the blocks
and switch to the JSON view.
Note that when we only have a single document
object in the request object, the builder software
automatically creates an array.
The array is required according to the Swagger file.
In addition, there are a couple of objects defined
by the Swagger file that only have
objects or arrays as children.
In other words, no scalar attributes.
The builder tool automatically creates these objects too.
Let's see two of them.
The first occurs when we add a signer recipient object.
You can see that a recipient's object
was automatically created.
In addition, an array was created for the single signer
recipient object.
In the same way when we add a Sign Here tab,
a tabs object was created.
The automatic object creation enables a simpler easier to use
diagram.
And fluent software.
As shown in the demo, the tool automatically
creates arrays as needed.
Here's an example of the builder tool automatically creating
an object to hold the signers array.
And the signers array was automatically
added to hold the signer object from the block.
DocuSign uses the open source code gen software
to autogenerate its SDKs from the Swagger file.
In turn, the builder tool uses recursion to autoprogram
the SDK source from the JSON, starting with the deepest leaf
nodes.
Just three methods are needed to adapt the auto programmer's
output to the different SDK languages.
This part turned out easier than I expected.
For example, you can see the deepest leaf
node in the JSON on the left is programmed as the first SDK
call on the right.
The auto programmer walks the JSON tree,
covering all branches to produce the SDK output.
For strongly typed languages, such as this C# example,
the autoprogrammer includes the type information.
The tool now auto programs SDK calls for C#, Java, PHP,
Node.js, and Visual Basic.
Support for more languages is planned for the first release.
So good news.
The builder tool has accomplished
all of its design goals.
Building the builder tool.
I've mentioned the API Swagger file several times.
The raw Swagger file is not directly used
in the builder tool.
Instead, the data that's needed is
extracted by a batch configuration
app that's rerun for each new version of the Swagger file.
The configuration app creates the JavaScript source
for the blocks, the tool box, and the relationship records.
The tool itself is a single page React application
with the DocuSign in-house styling library.
There are no significant server components.
The tool makes direct calls to DocuSign via CORS.
One of my goals was to use a tool to experiment
with browser-based software.
I'm happy that I was able to process both documents
and the diagram files entirely within
the browser-based application.
This includes creation of diagram files,
including their documents for download
to the desktop from the browser-based builder tool.
We showed an early version of the builder tool
to developer customers last year and the feedback was positive.
The tool includes an NPS survey and will enable developers
to supply additional feedback.
The first public release is planned for this summer,
with publication of the source next year.
That's it.
Thank you very much.