How can I control API output?

Learning objectives:

  • Return data from an endpoint.
  • Return text from an endpoint.
  • Return an image from an endpoint.
  • Return something else from an endpoint.


  • Vocab: “Serialize” = “translate into a format for storage or transmission”
  • Default = json via jsonlite::toJSON()
  • #* @serializer NAME list(ARGS)
    • eg, #* @serializer json list(na = "string")
  • Impacts behavior AND Swagger docs

Structured text

@serializer processed with content type
json (default) jsonlite::toJSON() application/json
unboxedJSON jsonlite::toJSON(
  auto_unbox = TRUE)
geojson geojsonsf::sfc_geojson() or geojsonsf::sf_geojson() application/json
yaml yaml::as_yaml() text/x-yaml
csv readr::format_csv text/csv
tsv readr::format_tsv text/tab-separated-values

Larger data

@serializer processed with content type
rds base::serialize() application/rds
feather arrow::write_feather() application/vnd.apache.arrow.file
parquet arrow::write_parquet() application/parquet


@serializer processed with content type
html (unprocessed) text/html; charset=UTF-8
htmlwidget htmlwidgets::saveWidget() text/html; charset=UTF-8

Use html for xml-structured data, too

Plain text

@serializer processed with content type
text as.character() text/plain
format format() text/plain
print print() text/plain
cat cat() text/plain

Devices (images & PDFs)

@serializer processed with content type
jpeg jpeg() image/jpeg
png png() image/png
svg svg() image/svg+xml
tiff tiff() image/tiff
bmp bmp() image/bmp
pdf pdf() application/pdf

Can define new image serializers with serializer_device()

Other things

@serializer processed with content type
contentType (user-specified) (user-specified)
octet (as is, must be raw) application/octet-stream
#* @serializer contentType list(type = "application/protobuf", serialize_fn = protolite::serialize_pb)
  • octet is contentType with a serialize_fn that checks is.raw()

Meeting Videos

Cohort 1

Meeting chat log