Catching up on REST

Many network-based web services offer APIs that comply with the REpresentational State Transfer (REST) design style. APIs that comply with REST constraints are called RESTful.

RESTful APIs are attractive because they leverage existing HTTP infrastructure, the same infrastructure and protocols that browsers use. As a result, a RESTful API has access to a great variety of resources (applications, libraries, developers, etc.). From an end-user perspective, you can use your existing browser as a client to access server databases. Developers like RESTful APIs because it is easy to integrate server data and resources into applications.

Music services often use RESTful APIs to provide metadata about artists and musical tracks. Offering this data through a REST interface makes it very easy to build a client application that will receive and display the information. This article shows how to query music data through a RESTful API.

Why REST

A RESTful API allows the client to retrieve data from the server without needing to know details about the server back-end implementation. There is no need for the client to know which server or database management software is used. In addition, the API enhances security by restricting who can access data and selectively restricting which data is accessible.

RESTful APIs operate in two modes, request and response. The client sends a request to the server for data. The server then responds with a status code, and if appropriate, the requested data.

In a RESTful web service, requests made to a resource's URI elicit a response with a payload usually formatted in HTML, XML, or JSON. The most common data transfer protocol for these requests and responses is HTTP, which provides operations (HTTP methods) such as GET, POST, PUT, PATCH, and DELETE. See the box entitled "More on REST" for additional background on RESTful APIs.

Music APIs

Several well-known music services provide RESTful API database access to musicians and to partners who want to integrate their content or music into commercial products.

Spotify, for example, provides an API that allows hardware partners to develop applications for home audio systems, music players, headphones, and other internet-enabled devices. According to the Spotify for Developer website, "Spotify Web API endpoints return JSON metadata about music artists, albums, and tracks, directly from the Spotify Data Catalog."

SoundCloud is a music service that allows musicians to share their music with a community of artists and listeners. Musicians can use the API to upload and manage their music for listeners.

MusicBrainz views its service as an open encyclopedia for music metadata. MusicBrainz is modeled after Wikipedia in that it is community-driven [2]. The metadata content is primarily, but not exclusively, targeted at music player and tagger applications. In this article, I will use the open source MusicBrainz API to request and receive music data through HTTP. (See the "HTTP Primer" box for more on accessing resources through HTTP.)

HTTP Primer

In order to understand RESTful APIs, it is essential to understand the role that HTTP plays. The Hypertext Transfer Protocol (HTTP) is a stateless application-level protocol for distributed, collaborative, hypertext information systems [3]. HTTP was designed, from its beginning in 1990, to support the client-server model (Figure 1), with requests passing in the form of messages from a client to a server. A response message and status code then passes from the server to the client.

Figure 1: HTTP supports the client-server model.

When HTTP was first introduced, the only method used to send requests was the GET method. HTTP has since evolved to include additional methods to allow requests to modify and delete content on the server. Among the methods currently used are: GET, POST, PUT, and DELETE (Table 1).

When a request message is sent by a user agent (the client application) to a server, the message typically contains header fields that can include metadata such as: method, target hostname, content type, content length, and other characteristics of the client, host, or message.

Upon receiving a request from a user agent, the server determines whether it can accept the request. If accepted, the server responds by sending a status code and a message back to the client. Response message content might include metadata or the requested target resource.

MusicBrainz API

The MusicBrainz API gives the client access to a wide range of music metadata about artists and their music, including biographical information, release dates, and media formats. Requests are in the form of a URL that is comprised of multiple components, some mandatory and some optional [4].

REST constraints require the API to be stateless. This means that each request sent by the client to the server must contain all the information the server needs to respond appropriately. As a consequence, all the necessary information is contained in the URL. In the case of MusicBrainz, the syntax for the URL is as follows:

<api_root><entity><mbid><inc><format>

<api_root> is the partial URL to the API, in this case:

https://musicbrainz.org/ws/2/

<entity> is one or more information categories, such as artist, recording, release, etc. <mbid> is the MusicBrainz identifier that is unique to each target resource in the database. <inc> is an optional subquery string. <format> is an optional format string that specifies the transfer format, which can be either JSON or XML. (XML is the default format.)