Skip to content

Latest commit

 

History

History
94 lines (62 loc) · 3.13 KB

body.md

File metadata and controls

94 lines (62 loc) · 3.13 KB
Raw

Body

Text data

In its simplest form, the request's body can be set as a String. By default, this method will:

  • use the UTF-8 encoding to convert the string to a byte array
  • if not specified before, set Content-Type: text/plain
  • if not specified before, set Content-Length to the number of bytes in the array

A String body can be set on a request as follows:

basicRequest.body("Hello, world!")

It is also possible to use a different character encoding:

def body(b: String)
def body(b: String, encoding: String)

Binary data

To set a binary-data body, the following methods are available:

def body(b: Array[Byte])
def body(b: ByteBuffer)
def body(b: InputStream)

If not specified before, these methods will set the content type to application/octet-stream. When using a byte array, additionally the content length will be set to the length of the array (unless specified explicitly).

.. note::

  While the object defining a request is immutable, setting a mutable request body will make the whole request definition mutable as well. With ``InputStream``, the request can be moreover sent only once, as input streams can be consumed once.

Uploading files

To upload a file, simply set the request body as a File or Path:

def body(f: File)
def body(b: Path)

Note that on JavaScript only a Web/API/File is allowed.

As with binary body methods, the content type will default to application/octet-stream, and the content length will be set to the length of the file (unless specified explicitly).

See also multi-part and streaming support.

Form data

If you set the body as a Map[String, String] or Seq[(String, String)], it will be encoded as form-data (as if a web form with the given values was submitted). The content type will default to application/x-www-form-urlencoded; content length will also be set if not specified.

By default, the UTF-8 encoding is used, but can be also specified explicitly:

def body(fs: Map[String, String])
def body(fs: Map[String, String], encoding: String)
def body(fs: (String, String)*)
def body(fs: Seq[(String, String)], encoding: String)

Custom body serializers

It is also possible to set custom types as request bodies, as long as there's an implicit BodySerializer[B] value in scope, which is simply an alias for a function:

type BodySerializer[B] = B => BasicRequestBody

A BasicRequestBody is a wrapper for one of the supported request body types: a String/byte array or an input stream.

For example, here's how to write a custom serializer for a case class, with serializer-specific default content type:

case class Person(name: String, surname: String, age: Int)

// for this example, assuming names/surnames can't contain commas
implicit val personSerializer: BodySerializer[Person] = { p: Person =>
  val serialized = s"${p.name},${p.surname},${p.age}"
  StringBody(serialized, "UTF-8", Some("application/csv"))
}

basicRequest.body(Person("mary", "smith", 67))

See the implementations of the BasicRequestBody trait for more options.