Create an API Notebook

An API Notebook is a web-based tool for building interactive tutorials and examples in a JavaScript scripting workspace. 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, as described in the API Notebook documentation.

In this tutorial, you create an API Notebook to connect to a RAML-based API managed by API Manager.


To create the API Notebook in this tutorial you need:

You can create an API Notebook using the API Notebook page. You can also create and add an API Notebook to an API portal as you design the portal. This tutorial creates a Notebook from the API Notebook page.

To create API Notebook:

  1. Go to the API Version details page of an existing API. For example, go to the T-Shirt Ordering Service version details page, click Edit portal, and on the Add drop-down, select API Notebook.

    The API Notebook canvas appears.

  2. Although a default client already exists for documentation purposes, create another one: Hover over the greyed-out, circular widget above the code cell, and click Insert API Client.


    The Insert an API Client dialog appears.

  3. Enter the API name T-Shirt Ordering Service in the search box, scroll to the T-Shirt Ordering Service item in the list that bears the name of your organization, and click Add.

    The API Client code appears in the code cell prefaced by a comment that looks something like this:

    // Read about the T-Shirt Ordering Service at
    API.createClient('tShirtOrderingService', '');

    A prompt below the code tells you how to explore the API.

  4. Follow the prompt to create a new code cell. Hover over the cell to display the menu icon, and select New Cell.

  5. In the new code cell, and type the name of the API. For example, type tShirtOrderingService in the cell.

  6. Execute the code cell: Select the hamburger menu on the right of the cell and select Execute.


    The following response containing the names of your resources appears:

    function (a,b){var c=f(a||"",b||{}).replace(/^\/+/,"").split("/");return L(d.extend([],e,c),{},D)}
    !client: Object
    !config: Object
    arguments: null
    caller: null
    length: 2
    name: "g"
    orders: Object
    products: Object
    prototype: g
  7. Expand !config to see the URL of the API.

  8. Add a code cell and enter the following function to post an order using the example order information in the RAML:{"size": "M","email": "","name": "Robin Pille","address1": "77 Geary St.","address2": "Apt 7","city": "San Francisco","stateOrProvince": "CA","country": "US","postalCode": "94131"})
  9. Select Execute from the cell’s hamburger menu.

    The response is:

    Object {"body": Object, "status": 200, "headers": Object}
    body: Object
    headers: Object
    status: 200
  10. Add a new code cell and type in the following code:

    var shirts = tShirtOrderingService.orders.orderId('4321');

    Use the autocomplete choices as you type. To add a line break within the cell, press Shift + Enter.

  11. Click Save.

API Notebook is published on the Developer portal.

Using API Notebook

  1. After editing an API Portal to add API Notebook, click Live Portal.

    The Developer portal for the T-Shirt Ordering Service appears.

  2. Select API Notebook from the list of visible components.

  3. Click Play notebook to execute the Notebook code. The results reveal information about your API based on the RAML.

Copying and Sharing an API Notebook

You can save an API Notebook to GitHub as a gist.

  1. On the Developer portal for the API, at the bottom of a published API Notebook, click Make your own.

    A copy of the Notebook appears.

  2. Click save.

    The Authenticate Notebook dialog says: Notebooks are saved as gists to your GitHub account. Authorize this application to save, edit, and share your notebooks.

  3. Click Authorize With GitHub and follow the GitHub prompts to authorize access to your account to save the notebook.

To share or embed your Notebook, click share.

You are offered two links, one for sharing the URL, the other for embedding the Notebook into any site.