What are the main types accepted by the Fetch API for the HTTP request body?

Question

I know I can use the API fetch to perform HTTP requests by browser.

And I know I can use the property body to configure the body of the request. But I would like to better understand which types I can use in this property.

Also, what is the relationship of each type accepted with the header Content-Type that the server expects?

Answer 1

The estate body is responsible for defining the body of the request to be made by fetch. The type of data you can pass to this property is varied, so it accepts:

1. FormData
2. URLSearchParams
3. USVString
4. Blob
5. BufferSource
6. ReadableStream

The first three are the most common. It is relatively rare to use Blob, BufferSource and ReadableStream day to day, but know that if you need them, they exist.

Below I will explain, enter FormData, URLSearchParams and USVString, which is the most suitable for each situation.

Utilise FormData (multipart/form-data)

Use the type FormData in the request body property when the server accepts requests whose Content-Type be it multipart/form-data. That one Content-Type is commonly used when any of the body fields is a file.

The user interface is extremely simple, since the constructor FormData accepts an element as argument HTMLFormElement, that will have the fields serialized.

An example:

// Seu elemento <form>:
const form = document.querySelector('#my-form');

fetch('https://path.to/resource', {
  method: 'POST',
  body: new FormData(form)
})
  .then(...)
  .catch(...);

Note that when you pass an instance FormData to the property body, the header Content-Type is already automatically set to multipart/form-data.

Utilise URLSearchParams (urlencoded)

Use the type URLSearchParams for requests in which the Content-Type expected is application/x-www-form-urlencoded.

An example:

// Seu elemento <form>:
fetch('https://path.to/resource', {
  method: 'POST',
  body: new URLSearchParams({
    field1: 'Value1',
    fieldN: 'ValueN'
  })
})
  .then(...)
  .catch(...);

When using URLSearchParams in body, the header Content-Type is automatically set to application/x-www-form-urlencoded.

Note that the builder URLSearchParams does not accept a form instance directly (as well as FormData makes). You can pass an object with keys and values, which will be correctly serialized (as shown in the example above). Another option, as documented, is to pass an instance of FormData to the builder URLSearchParams, then the serialization of an entire form also becomes trivial:

const myForm = document.querySelector('form#my-form');
const urlEncodedBody = new URLSearchParams(new FormData(myForm));

// Passe `urlEncodedBody` para a propriedade `body` da requisição...

Utilise USVString (string as the body of the request)

The guy USVString nothing more than a different implementation of browser strings. Ignoring the technical part (which can be found in documentation), is basically the primitive type string Javascript. Thus, it is the type that should be used when, for example, you need to send content in format application/json.

An example:

fetch('https://path.to/resource', {
  method: 'POST',
  body: JSON.stringify({
    field1: 'Value1',
    fieldN: 'ValueN'
  }),
  headers: {
    'Content-Type': 'application/json'
  }
})
  .then(...)
  .catch(...);

Note that the JSON.stringify returns the primitive string Javascript. Before the request is executed, the implementation will convert the type string from Javascript to the USVString.

Note that how to pass a string to the property body is ambiguous (may represent several types of Content-Type different), the browser has no way to infer this header correctly. So, supposing that we want to make a request whose body is the type application/json, we need to provide the header explicitly.