API Notebook Reference

An API Notebook is a web-based tool for building interactive tutorials and examples in a JavaScript scripting workspace. Users do not need to install anything to explore the API from your Notebook. You present the Notebook on your API Portal to users of your API who can explore the API. API Notebook can generate an API client based on a RAML API definition, and through it perform authenticated live calls on a real server or on just an empty API interface. From the RAML definition, API Notebook obtains information about the API’s resources, methods, required arguments, and other things.

From your API Notebook, users can also create their own API Notebook for personalized testing of your API in their Github gist. Users can execute sequences of calls to an API for testing or other purposes.

First, you create an API client, based on a RAML API definition. Through the client, you perform authenticated live calls to an API, You can create multiple clients to call different APIs from the same Notebook.

Next, aided by code completion hints and prompting, you create code and documentation cells to test and explain the API. In code cells, you write JavaScript methods that expose the API resources and methods.

From a Notebook on your API Portal, users can save an API Notebook as a gist in a GitHub account and adapt it to their needs.

Anatomy of an API Notebook

Notebooks are composed of the following types of cells:

Text

These cells accept markdown. Use text cells to include documentation about Notebook functions.

Code

These cells accept JavaScript, including imported JavaScript libraries and functions from external libraries. Use code cells for executable blocks of JavaScript.

In a code type API. and pause to look at the code completion suggestions:

Type the following code:

API.createClient(alias, url, options? cb?)

As you type the createClient call, API Notebook offers the following suggestions. These are the attributes you can use in the createClient methods:

Parameter

Description

Req/Opt

alias

The name with which you call this client from now on

Required

url

A URL that directs to the API’s RAML definition

Required

options

A specification of default headers, a fallback body, or other option. Type the method in the notebook and place the cursor on this argument for more details.

Optional

cb

Pass in a custom callback to run when the client has loaded

Optional

The Notebook can call an existing API, as long as it’s published behind an HTTP endpoint. Through the MockingService you can call mocked APIs that are almost an empty shell to test out your API design.

The design of the API Notebook follows the literate programming paradigm: Code should be human readable as well as executable.

Creating a Notebook

There are two ways to create an API Notebook:

Edit an API portal. Create the Notebook within the portal using the left navigation of the portal to add a new API Notebook. A line of code that creates the necessary API client for your RAML-based API is generated when you add the API Notebook.

Use the following site to create a new Notebook: https://api-notebook.anypoint.mulesoft.com

Log in to your GitHub account.

Authorize your application to write to the gist.

Log into the https://api-notebook.anypoint.mulesoft.com site using your GitHub account credentials.

Create the API Notebook.

Click the save icon.

The API Notebook is stored as a GitHub gist.

Sharing API Notebooks

To share an API Notebook that you create in an API portal, share the API portal itself. Either make the portal public or give other users permissions to view it from the API version details page.

To share or embed your Notebook, click the Share icon. You are offered two links, one for sharing the URL, the other for embedding the Notebook in a site.

In this topic:

Sign up for our Dev newsletter

MuleSoft provides the most widely used integration platform for connecting SaaS and enterprise applications in the cloud and on-premises. Delivered as a packaged integration experience, CloudHub™ and Mule ESB™ (Enterprise Service Bus) are built on proven open source technology for the fastest, most reliable on-premises and cloud integration without vendor lock-in.