MyAPICalls: A sample app with a twist

The Developer Center team constantly strives to enhance our developer tools to help you get up to speed quickly on how to integrate your apps, sites, and systems with the DocuSign APIs. Our newest offering is the MyAPICalls sample app. Like our other sample apps, MyAPICalls is an interactive tool that enables you to experiment with API calls without writing code. But this app has a key difference. It shows you API request structure, updated onscreen as the calls are constructed. It also displays API responses. We’ve placed the requests and responses front and center in this app so that you can easily trace through their structure. You’ll see how return values from a call can be used in subsequent calls. MyAPICalls is also a great resource for learning how a series of API requests can accomplish common tasks. As an added bonus, this app creates sample data in your developer account, which can be useful for testing or demos.

Scenarios in the sample app

MyAPICalls has a collection of scenarios that you can run. Each scenario includes a sequence of API calls that implement a use case, such as creating an envelope from a template, creating and activating a clickwrap, and creating and testing a Connect configuration. The figure below shows a partial list of scenarios on the MyAPICalls home page.

MyAPICalls home page with list of scenarios

The scenarios include calls to these DocuSign APIs:

Scenarios that cover additional APIs will be added in the future.

Each scenario is constructed from a manifest file. This is a JSON file that specifies the API calls used, the parameter values included in the requests, and how those values are populated. Details about manifest file structure are beyond the scope of this post, but you can retrieve example manifest files from the app’s GitHub repository if you want to take a closer look.

Before you can run scenarios, you must log in with your DocuSign developer account. You can do this by selecting Log in in the upper right corner of the home page or on any other page in the app.

Note: When you execute scenarios, by default MyAPICalls stores API requests and responses in your browser’s local storage in order to display them in the UI. This includes your account ID, as well as any values that you supply in the MyAPICalls UI. These values remain in local storage even if you close the browser tab. The Disabling call execution logging section later in this post explains how to prevent the app from storing call data and how to clear local storage after you finish running scenarios.

Scenario execution

Selecting Try scenario on the MyAPICalls home page takes you to a scenario execution page. As shown in the figure below, you can expand the Behind the scenes panel on this page to learn about the API calls. For instructions to run the scenario, including any prerequisites, expand the Running the sample panel:

Scenario execution page with expanded Behind the scenes and Running the sample

The navigation menu on the left (see the figure below) gives you the option of running the entire scenario, which executes all calls consecutively, or running each step individually. A step corresponds to a single API call in the sequence of calls in a scenario.

Scenario execution page navigation menu

Running steps individually

Selecting the first step in the navigation menu takes you to the step execution page. In the Parameters list, you enter values that are required for the API call used in the step. The values are automatically added to the Request body area to the right (see the figure below). This shows the structure of the JSON request that will be sent in the call.

Step execution page

Selecting Execute sends the request to the DocuSign developer environment. You’ll see the API response in the Response body area:

Step execution page with Response body after executing the step

The API call execution list at the bottom of the page also shows the request, response, and other call information:

Step page API call execution list

After executing a step, select Next step to proceed to the next step execution page, where you can supply required parameters for the call and execute it. After you’ve completed all the steps, follow the instructions provided in MyAPICalls to see the results, including objects created in the DocuSign platform or documents that can be signed. For the embedded signing scenario shown in the screenshots, you can navigate to a URL where you can complete the signing process.

Running an entire scenario

As an alternative to executing a scenario step by step, you can run all the calls in a scenario consecutively from the scenario execution page (see Scenario execution above). From a step execution page, you can access the scenario execution page by selecting Execute scenario in the navigation menu. If you’re navigating to a scenario from the home page, the scenario execution page is displayed by default.

To run an entire scenario, MyAPICalls still needs values for every parameter used in the individual steps, but it presents them on a single page. Supply the required parameter values for all the calls in the scenario and then select Execute. The requests and responses will be listed in the API call execution list, as shown below.

Scenario execution page API call execution list

Running a scenario multiple times

On the scenario execution page, you can run a scenario multiple times by entering a value greater than 1 (the default) in the Number of iterations field, populating all parameters, and selecting Execute. This is useful for loading test data in your developer account—something you might need, for example, to demo a dashboard of API call activity. To create different call data for each repetition of the scenario, you can include either of these variables in your parameter values, and they will be replaced at run time with unique values:

  • {iteration}: will be replaced with the execution number. For example, during the first execution, it will be replaced with 1.
  • {random}: will be replaced with a random number.

The figure below shows an example of the {iteration} variable used in several of the parameter values. 

Configuring a scenario to execute multiple times with unique data

Disabling call execution logging

If you don’t want API requests and responses to be logged to the browser’s local storage, check the Execute without generating API call execution log option (shown in the figure above) on the scenario execution page. Checking this option also means that requests and responses won’t appear in the API call execution list. You might want to turn off logging, for example, when running the sample app on a public device. If you run scenarios with call logging enabled, you can clear saved call data from local storage by selecting Log out in the upper right corner of the MyAPICalls UI. Another option is to run MyAPICalls in an incognito browser session. When you close the session, local storage will be cleared.

Source code repository

Like the code for all of our sample apps, MyAPICalls source code is available for you to download and run. This gives you the option of modifying the scenarios from the hosted version of the app in your local repository to try different variations. You can also create your own scenarios and run them locally.

Suggestions welcome

We hope you’ll spend some time trying out MyAPICalls to see how it can help with your development process. We plan to add more scenarios to the hosted version, so we recommend checking back regularly. Please send suggestions for scenarios you’d like to see, or other feedback, to developers@docusign.com. You can also send feedback by opening an issue in the GitHub repository.

Additional resources

Julie Gordon
Author
Julie Gordon
Programmer Writer
Published