An Introduction to REST and the Mailchimp API

Background

When we talk about the Mailchimp API, we use terms like “REST” and “RESTful.” “REST” stands for Representational State Transfer. It is an architectural style that is an alternative to RPC or SOAP-based web services.

While there is no official REST standard, there are common approaches and best practices used across the engineering community that help define how RESTful APIs should work. For example, most RESTful APIs follow six specific constraints or design rules.

Most APIs are not fully RESTful, including the Mailchimp API. But Mailchimp follows most of the practices and common definitions of the style. For example, the Mailchimp API has what we call “resources,” which are typically nouns like “subscribers” or “campaigns.” You take action on resources using the standard HTTP methods: POST, GET, PATCH, and DELETE.

RESTful HTTP Methods

You may see these standard HTTP methods referred to as CRUD (or Create, Read, Update, Delete). Although CRUD has roots in database operations, you can also map those operations to the standard HTTP methods. For example, use a POST request to create a new resource, a GET request to read or retrieve a resource, a PATCH request to edit a resource, and a DELETE request to delete a resource.

RESTful Features of the Mailchimp API

Nouns

RESTful APIs are based on resources and share a well-defined and uniform interface. URLs and URIs in the API do not typically contain verbs because verbs cannot be resources. That is why we try to limit verbs to the HTTP method part of your request.

We also refer to “endpoints” in our documentation. Endpoints are URIs (as opposed to URLs) for individual resources. For example, find a collection of reports by requesting the /reports/ endpoint, or access individual reports at /reports/{campaign_id}.

HTTP methods and response codes

We do our best to use standard HTTP methods with accurate and well-known status codes in the Mailchimp API, but here are some additions and deviations:

  • GET requests are safe and will not alter a resource.
  • PATCH and DELETE methods are idempotent.
  • POST is not safe or idempotent.

If your firewall rules do not support HTTP methods, like PATCH or DELETE, use the X-HTTP-Method-Override header. Pass the method you want to use in the X-HTTP-Method-Override header and make your call using the POST method. The override will not work with any other method, so if you try and use the override header with a GET, PATCH, PUT, or DELETE method, you will receive an error.

Additionally, the 204 No Content error does not include JSON body content to parse. This is most common with DELETE requests, and could cause issues if your JSON parser does not handle empty responses well.

Self-Describing representations

We use JSON Schema to describe each representation, and every response has a LINK header that points to the self-describing schema. Schemas also contain validation and type information to help you error-check your requests.

Explore our JSON Schema documents in the API Playground, or view them directly at https://api.mailchimp.com/schema/3.0/Root.json.

Discoverable

The Mailchimp API is also fully-discoverable. This means you can start at the root, https://api.mailchimp.com/schema/3.0/Root.json, and click through the links displayed in the schema to discover more resources. We also include links in the resource representations returned by each successive call.

This type of discovery technique is often referred to as HATEOAS–Hypermedia As The Engine Of Application State. But we do not expect you to traverse the API to make calls, so you can make deep calls directly. HATEOAS is just a way to improve the first-time developer’s experience with the Mailchimp API.

Deviations from REST

Verbs we use

Some places in the Mailchimp API deviates from common REST guidelines. Completely removing verbs is not possible for every request, especially those related to sending a campaign. Although there are some RESTful workarounds we could use, they are typically more confusing than they are useful.

To address this, we break from REST architecture for certain actions. For example, to pause an Automation workflow, you would make a POST request to the /automations/{workflow_id}/emails/{id}/actions/pause endpoint. All action endpoints are namespaced this way.

Generic MIME types

Some companies use a custom MIME type for their RESTful APIs instead of the generic JSON type (application/json). The Mailchimp API uses the generic JSON content type, because the benefits of customization are more theoretical than practical.

Now that you know a bit more about the REST architecture and how we use it in the Mailchimp API, be sure to check out the API Reference and the Playground to start making requests.