MIME Types: What do They Say about HTTP Messages?

I get a lot of questions about media types (MIME types) when I help customers build integrations. Customers sometimes forget to include a Content-Type header when making requests to an API, or they send the wrong header and receive an error in response. Let's talk about what kinds of data you can send via an integration and how you declare the type of data you've sent.

Let's say that we've built an API and are sending HTTP messages to it. We send this as part of a message:

{
  "employee": {
    "eid": 7728,
    "lname": "Villarosa",
    "accruedhours": 172,
    "fulltime": true
  }
}

It appears that the data is JSON. But if we were to go with this ...

<employee>
  <eid>7728</eid>
  <lname>Villarosa</name>
  <accruedhours>172</accruedhours>
  <fulltime>true</fulltime>
</employee>

... it's now obviously XML.

The point is that both are human-readable, so if we don't include descriptive data, we can still understand them. However, there are hundreds of types of content that could be used in HTTP messages, and many are binary (so not human-readable except by Johnny Mnemonic).

To avoid confusing ourselves and any apps we use, we define the message contents as specific media types. This allows the receiving app or system to know the content type without fully parsing the message. Though the current term is media type, the original term was MIME (multipurpose internet mail extensions) type. It's also important to remember that we use media types everywhere, not only for HTTP messages.

While many of us are accustomed to thinking of files in terms of their extensions (.docx for MS Word, for example), browsers, websites, and web apps think of files in terms of media types. As a result, a .docx file is described as application/vnd.openxmlformats-officedocument.wordprocessingml.document. This construct might seem unwieldy for us, but it is what an app needs to know.

What is a media type?

A media type is a string that defines the nature and format of a document, file, or other collection of bytes. A media type has two parts: type and subtype.

The type represents the primary category, including things such as application, audio, or text. The subtype further narrows the content. For example, we might have application/json, audio/mpeg, and text/plain.

There is also a unique media type that we should use when working with binary data, and we either don't know the media type or know that there is no corresponding media type. This special media type is application/octet-stream.

How do we use media types for HTTP messages?

We place the media type string in the header of an HTTP request. Here's one for JSON:

Content-Type: application/json

An example HTTP request, with full context, is as follows:

POST <https://api.example.com/customers> HTTP/2.0
User-Agent: slainte
Host: localhost:1234
Content-Type: application/json

{
  eid:7728,
  lname:'Villarosa'
}

This example uses POST to submit customer data to the API and notifies the API that we are providing JSON data.

What if we need HTTP responses in a particular media type?

While we use Content-Type in an HTTP header to describe the media type in the same message, we can use Accept in a request to an API to tell it that we need to have its response conform to a certain media type. Here's what that might look like:

GET <https://api.example.com/customers> HTTP/2.0
User-Agent: slainte
Host: localhost:1234
Accept: application/json

This example uses GET to request a list of customers from the API and notifies it that we expect the data in JSON format.

However, asking for something does not guarantee we'll receive it. Each API has constraints for media type usage. As a result, we should first consult the API documentation to ensure JSON is on the list of supported media types for api.example.com.

What about multipart types?

Most media types (including all of the above examples) are called discrete media types. That is, they describe sending single data collections or files. However, there is another category of media types called multipart.

This media type is used for HTTP messages which consist of multiple collections or files, each one of which can have a different discrete media type.

Here is an example of a multipart type used to send both JSON data and a PNG file.

POST <https://api.example.com/customers> HTTP/2.0
User-Agent: slainte
Host: localhost:1234
Content-Type: multipart/form data;boundary="76in9i2w314r"

--76in9i2w314r
Content-Disposition: form-data; name="customer"
Content-Type: application/json

{
  eid:7728,
  lname:'Villarosa'
}

--76in9i2w314r
Content-Disposition: form-data; name="customer-photo"; filename="8ywe683.png"
Content-Type: image/png

{file content in binary form}

--76in9i2w314r--

What happens if we use the wrong media type?

We touched on the fact that each API can support different media types. If API documentation becomes outdated, or we're simply not paying close attention, we might submit an HTTP message which contains a media type that the API doesn't recognize.

Let's say we submit an HTTP message with an application/octet-stream media type, but the API does not accept it.

We should get back an error response like the following:

{
  "code": 415,
  "message": "HTTP 415 Unsupported Media Type"
}

Do we have to use media types?

Writing the code for a system so it can automatically parse data collections submitted to it is extra work and increases the processing time for involved systems. Using media types does away with that additional effort and ensures consistency in working with different APIs.

For more content on media types and other integration topics, check out our guide to API integrations.

Want to learn more about API integrations?

Download our API Integrations Guide to see what an API integration is and learn how it works.

Get my Copy