Introduction

The core features of Max/Msp are super powerful. However, having the ability to work with data outside the environment is a tremendous benefit. Leverage the power of external web servers, download or upload files.This article will explore basic communication between Max and the web by calling a publicly available API.

This is a great subject to tackle a lot of the flexibilities of max. With basic knowledge of Max, following this tutorial will be easy. We will also offer variations of this patch for intermediate and advanced usage in following articles.

What is an API?

Not to be confused with the API audio consoles, an “Application Programming Interface” is essentially the doorway for developers to work with coding-libraries, and allows websites to communicate with one another. API’s can be a basic process as returning simple text or as complex as the Google Analytic Reports API. The main objective is always the same; make a request to a web server that performs a task and response a response with the data we want.

1. The API is triggered by the developer, app or website
2. The API performs the process on the backend
3. The API returns a response to the developer, app or website

Making an API Request

A web API, such as the Jokes API, is triggered by a URL request. Calling this API will, you guessed it, tell jokes! Good jokes about Chuck Norris. Some requests available can include ‘parameters’ that may be required or optional. The parameters will instruct the API about specifics to help identify the data to respond with. Investigation of an API is always required to know the requests or parameters available.

Fetch a Random Joke
http://api.icndb.com/jokes/random

The above URL requests a random joke from the Jokes API. The response can immediately be seen by visiting the URL in any browser. The format of the response will typically be in JSON or XML format. These formats are industry standard. It has “key-value based” like a dictionary. For every term there is a definition.

The response will be difficult to read especially with larger data-sets. With the right browser extension, JSON or XML data can be “parsed” for easier reading. This also helps demonstrate the key-valued structure of the data.

See the ID? That number can actually be used as a parameter to request a specific joke with a different URL. Look back at the Jokes API documentation, to find the URL to request a specific joke.

Request Specific Joke with the the ID at the end
http://api.icndb.com/jokes/183

The Most Basic Patch

In Max, there are always many ways to achieve the same outcome. For this first demonstration, the patch will consist of only core max objects without any javascript or dictionary objects. This is as basic at it gets.

1. “MaxURL” object can make requests to the web. Connecting a message object with “get http://api.icndb.com/jokes/random” to the inlet is all that is needed to make a basic url request to the Jokes API.
2. The response will include data from the API. However, there is also a lot of extra browser protocol data that we don’t need. “dict.unpack” will extract exactly what we want from of the response, in this case, the “body”. The body is the section that the any website intends for us to use. The format of the response will be dependent on how it was developed. In most scenarios it will be XML or JSON but it could be returned as unformatted text. In that case, we use “dict.serialize” object to format the data appropriately.
3. Finally, extract the joke the same way we did the body and push the result to a comment object. For good fun, set the comment object to have a bubble background and include a smile emoji for comic-style effect.

Conclusion

There is no shortage of intro tutorials of Max/MSP. Every new youtube series covering max feels the need to “start over” from zero. For any experienced user waiting for new and better content, this is extremely frustrating! Hopefully this tutorial offered the basics of an advanced subject that is suitable for all levels.

In the next tutorial we will redesign this patch using 2 other methods. Stay tuned!