An Introduction to REST

Background

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

While there’s 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 aren’t fully RESTful, including the MailChimp API. But we follow 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 don’t typically contain verbs because verbs can’t be resources. That’s 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 lists by requesting the /lists/ endpoint, or access individual lists at /lists/{list_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 won’t alter a resource.
  • PATCH and DELETE methods are idempotent.
  • POST isn’t safe or idempotent.

If your firewall rules don’t 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 won’t work with any other method, so if you try and use the override header with a GET, PATCH, PUT, or DELETE method, you’ll receive an error.

Additionally, the 204 No Content error doesn’t include JSON body content to parse. This is most common with DELETE requests, and could cause issues if your JSON parser doesn’t 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

Our 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 hypermedia 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 don’t 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

In some places in the MailChimp API, we need to deviate from common REST guidelines. Completely removing verbs isn’t possible for every request, especially those related to sending a campaign. Although there are some RESTful workarounds we could use, they’re 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 or vendors will use a custom MIME type for their RESTful APIs instead of the generic JSON type (application/json). For the MailChimp API, we use the generic JSON content type, because the benefits of customization are more theoretical than practical for our API.

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.