Larry Kluger - Exploring an API with Blocks

API the Docs Virtual Event Series 2020 Recap

This talk was presented at API The Docs Virtual 2020 event series on 10 June. We are glad to present the video recording, slide deck and talk summary below. Enjoy!

Visit our talk recaps ToC page for an overview of all presentations!

Larry Kluger

Lead Developer Advocate at DocuSign

Larry's presentation



Larry's slides



What’s an API Explorer?

An API “Playground” Enables you to try out a company’s API from the browser without writing any software or script. API Explorers are tools for making live calls to the API endpoints.

Some devportal refer to their API Reference documentation website as an API Explorer. So, “API Explorer” is also used for static API documentation.


Primary benefits of API Explorers:

  • Quick tryout of the company’s API
  • Best Explorers include typed forms with select boxes and numeric entries
  • User eXperience features help to create correct API requests
  • Short forms documentation with links to more extensive documentation

Text areas for creating API request:

  • Benefits:

    • Easy to save and reuse the request
    • Supports nested objects

  • Issues:

    • More thinking is required
    • Easier to make an error
    • The explorer is no longer click&go
    • Text format has no guardrails -- you’re programming not exploring
    • APIs with many nested objects: the form UX can be problematic

Goals

  • An API Explorer that supports:

    • Click&go (click configuration), easy request creation
    • Supports deeply nested API elements (arrays and objects)

  • Additional features in the tool:

    • Include access to the API documentation
    • Show the completed request as JSON
    • Auto-program the request using an SDK in multiple languages
    • Load pre-built examples and then modify them to meet more specific developer needs
    • Save your work for re-use
    • Share your examples to help others

Solutions

To have an API Explorer that supports click configuration and deeply nested API elements:

  • Use the open source Google Blockly library that enables an easy update of the library

  • Use the builder pattern to add data to the request object - the user does not have to worry about erase, child or grandchild objects

  • As result: the blocks are easy to edit and form the most complicated API requests

  • Each block includes a small JavaScript function - altogether the blocks create a fluent (chained) output program

  • An additional layer of software takes the fluent input and produces the JSON output

Switch view

(e.g. from Node.js to JSON)

  • Automated array creation: the Builder tool uses the Swagger file definitions to automatically create arrays as needed

  • Automatic object creation:

    • Objects that have no scalar attributes can also be automatically created
    • Automatic arrays and objects simplify the diagram (blocks) and the fluent program

  • Auto-programming the API’s SDK: CodeGen software generates SDKs from the OAS and the Builder tool uses recursion to auto-program the SDK

Building the Builder tool

  • The tool is built from the API’s Swagger file (OAS): as a separate batch process, a configuration app parses the Swagger file and creates the block definitions.

  • No significant server component. The tool makes direct calls to DocuSign via CORS.

  • Single page React application with the Docusign inhouse-style library

See the Builder Tool demo in the presentation to find out how DocuSign could meet the goals.

Sign up to our Developer Portal Newsletter so that you never miss out on the latest API The Docs recaps and our devportal, API documentation and Developer Experience research publications.