API Notebook Release Feb. 27th: **Breaking Changes**


I’m happy to announce that on February 27th we released several API Notebook updates including greatly improved syntax and usability for generated API clients.

Unfortunately, this updated syntax includes several breaking changes and some non-breaking changes, but with these changes the syntax will remain stable for the foreseeable future. In order for your existing notebooks to continue functioning after this release, it may be necessary to make updates.

If you run into any issues, find bugs, or have other feedback on the changes, please post in this forum.

###Release Summary###

Breaking Changes

  • Authentication method update
  • Request method syntax changes
  • New API Client configuration
  • mediaTypeExtension support - no more using it as a function, just use .json!

Non-Breaking Changes

  • Improved test coverage
  • Tool-tips/in-line help for API resources and calls
  • Bug fixes

Breaking Change Details

Additional documentation around the new syntax will be released in the future, but the breaking changes are described here in some detail.

For the examples below, assume we have created an API client, instagramApi

Authentication now uses the method API.authenicate(client, method, options), and will auto-detect the authentication type based on the API’s RAML definition

Previously you would authenticate using


Now you authenticate using


Request Methods that do not accept bodies (e.g. GET) now use the syntax: <api-client>.<resource>.<method>(query, options, async). Request methods that accept bodies (e.g. POST) now use the syntax: <api-client>.<resource>.<method>(body, query, options, async).

Query parameters are now handled by passing in an object for the query argument, and headers and options by the options argument. Valid option keys are proxy, body, baseUriParameters, headers, and query.

In this example we are passing in a query and using options to both set proxy behavior for this call and pass in a header

instagramApi.tags.search.get({count: 10}, {proxy: false, headers: {apikey: "myAPIke712345"}});

API Client Configuration has also been updated. You can now configure default options for your API client using the API.set(client, key, value), API.unset(client, key, value), and API.get(client, key, value) methods. Valid option keys are proxy, body, uriParameters, baseUriParameters, headers, and query.

In this example, we tell the notebook not to route calls to this API through the proxy

API.set(instagramApi, 'proxy', false);

Media Type Extension Support has been added. Instead of using the media type as a function, now you simply use .json, .xml, etc.

For the Twitter API, which requires media extensions, before we would have called

twitter.statuses.update(".json").post({status:"This is a new Tweet"});

Now we call

twitter.statuses.update.json.post({status:"This is a new Tweet"});

Examples for API Notebook?

This topic is now pinned. It will appear at the top of its category until it is either unpinned by a moderator, or the Clear Pin button is pressed.

unpinned #3