Nav

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:

creating-an-api-notebook-4f42a

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

agent

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: link:https://api-notebook.anypoint.mulesoft.com

    1. Log in to your GitHub account.

    2. Authorize your application to write to the gist.

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

    4. Create the API Notebook.

    5. Click the save icon.

      notebook2.png

      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.

notebook3.png

To execute all code cells in your Notebook sequentially, click Play.

play