Contact Us 1-800-596-4880
  1. Homepage
  2. Exchange
  3. Document an API

  4. Document an Asset Using API Notebook

Document an Asset Using API Notebook

API Notebook lets you document an API’s functionality with explanations that accompany code windows. Users can change the code and execute it by clicking the Play button in each code block. You can create a new API Notebook from the Exchange editor and use JavaScript code in the code blocks.

Use API Designer in Anypoint Platform to improve and test your RAML, OAS, or AsyncAPI API specification, and to publish the API specification to Anypoint Exchange.

An OAS specification is converted into RAML so you can follow the RAML conventions in API Notebook. Also, the RAMl specification is converted when you upload an OAS.

  1. Click the asset to view details.

  2. Click Edit documentation and click the API Notebook icon Icon - API Notebook in the Editor in the editor.

  3. Add a description for the asset.

  4. In the Visual editor, the API Notebook icon creates a panel where you can add JavaScript code items. Enter the first letter of the function you want to add and Notebook lists the available functions starting with that letter.

    If you are using Markdown, each notebook entry is enclosed in a block of 3 tick marks, for example:

    ```notebook
// Authenticate client
API.authenticate(myclient);
```

API Notebook Program Flow for External APIs

If you are accessing an external API such as the Instagram API, fetch the client using the Anypoint Asset Portal Service at the https://anypoint.mulesoft.com/exchange/api/v1/health URL.

The fetch code is:

fetch('https://anypoint.mulesoft.com/exchange/api/v1/health').then((res) => res.json())

Enable users to authenticate with the API:

// Authenticate Instagram.
// This asks you to authenticate with your personal account.
// Don't worry, we have no idea who you are.
API.authenticate(instagramApi);

You can then construct your notebook to use the API.

API Notebook Program Flow for API Manager APIs

  1. Create a client in the notebook to initialize access to your API using the API.createClient function.

    Syntax: API.createClient('CLIENT_NAME', 'URL_TO_API_MANAGER_API');

  2. Authenticate the client with Anypoint Platform using the API.authenticate function.

    Syntax: API.authenticate(CLIENT_NAME);

  3. Create your notebook based on the functionality in your REST API. Each function is based on the names of your RAML descriptor blocks. For example, for the getdetails client and with a block called /info, to document the GET call, the function description in the notebook is: getdetails.info.get();

    You can add extra parameters to function call with an array, for example:

    me.function.post[{ orgId: 'myorg'}) …​]

  4. Test the API in Exchange by setting elements in the code blocks and clicking Play. Ensure all code blocks work without causing errors in the code.

The create and authentication calls must be in separate notebook calls:

```notebook
fetch(’https://anypoint.mulesoft.com/exchange/api/v1/health').then((res) => res.json())
API.createClient(‘github’, ‘https://anypoint.mulesoft.com/apiplatform/repository/v2/organizations/ORG_ID/public/apis/7782/versions/7918/files/root’);

```

```notebook

API.authenticate(github);
``` (edited)

API Notebook Security

API notebooks run plain JavaScript in the browser. To ensure sensitive data does not leak, API Notebook disables certain JavaScript functionality:

  • All global functions, including alert and prompt

  • All global variables, including window, document, localStorage, and XMLHttpRequest

See Also