--- title: "Get started with zujson" description: "Take one response body through parsing, writing, raw bytes, errors and NDJSON." output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{Get started with zujson} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r, include = FALSE} knitr::opts_chunk$set(collapse = TRUE, comment = "#>") ``` ```{r setup} library(zujson) ``` We take the kind of JSON body an API returns, read it into R, write some of it back out, and see what happens when a body is broken. By the end you will have met the seven functions that do most of the work, and the rule that decides what each JSON value becomes in R. The full type mapping, the limits and the differences from jsonlite are left to the help pages and the articles listed at the end. ## Parse a response body Here is a small response: a count, a cursor that is `null`, and two records. ```{r} body <- '{ "total": 2, "cursor": null, "items": [ {"id": 1, "name": "Ada", "tags": ["admin", "dev"], "score": 9.5}, {"id": 2, "name": "Grace", "tags": [], "score": null} ] }' ``` `json_parse()` turns it into R. Look at what each kind of JSON value has become: ```{r} res <- json_parse(body) str(res) ``` A JSON **object** is a named list, and `null` is `NULL`. A JSON **array** is an atomic vector when its elements are all strings, all numbers or all logical values, which is why Ada's `tags` is a character vector. Any other array is a list, which is why `items`, an array of objects, is a list of two records. Grace's empty `tags` has no element to take a type from, and is an empty logical vector. A whole number is an integer, and any other number a double. The type of a value is never changed to make a vector. An array that mixes numbers and strings stays a list, with the number still a number: ```{r} str(json_parse('[1, "Ada"]')) ``` `?json_parse` has the complete mapping, and the `simplify` argument that changes this rule. ## Get records as a data frame An array of objects is how an API sends a table. With `data_frame = TRUE`, `json_parse()` builds a data frame from every such array, wherever it sits in the document. Here it is `items`: ```{r} json_parse(body, data_frame = TRUE)$items ``` Each key is a column. `score` was `null` for Grace and is `NA` here, and `tags`, which holds a vector per record, is a list column. ## Write a request body `json_write()` goes the other way and returns the JSON as one string, which `cat()` prints without R's escapes. We build the body of a request that adds a third record: ```{r} new_item <- list(name = "Edsger", tags = "dev", active = TRUE) cat(json_write(new_item)) ``` A list whose elements are all named is written as an object; a list or vector without names is written as an array, except that a vector of length one is written as a bare value. So `tags` came out as a string. The API sent `tags` as an array, so we wrap it in `I()` to keep it one: ```{r} new_item$tags <- I("dev") cat(json_write(new_item)) ``` Writing `res`, the response we parsed, and parsing the result gives back the same R object: ```{r} identical(json_parse(json_write(res)), res) ``` ## Send and receive bytes An HTTP client hands you a response body as a raw vector and wants a request body as one. `json_write_raw()` returns UTF-8 bytes, and `json_parse()` accepts them as it accepts a string: ```{r} bytes <- json_write_raw(new_item) head(bytes) str(json_parse(bytes)) ``` The one-element array we wrote for `tags` reads back as a character vector of length one. When the JSON is in a file, `json_parse_file()` reads it without the detour through a string: ```{r} path <- tempfile(fileext = ".json") writeBin(bytes, path) json_parse_file(path)$name ``` ## Handle a broken body A connection that drops leaves you with part of a body. We cut ours off after 40 characters. `json_validate()` says whether the input is JSON, without building anything and without raising an error: ```{r} truncated <- substr(body, 1, 40) json_validate(truncated) ``` `json_parse()` stops, and the message says where: ```{r, error = TRUE} json_parse(truncated) ``` Every error zujson raises has the class `zujson_error`, and a more specific one before it, so a single handler can catch them all and still tell them apart: ```{r} tryCatch( json_parse(truncated), zujson_error = function(e) class(e)[1] ) ``` ## Read and write NDJSON **NDJSON** is one JSON value per line, the format of log streams and bulk uploads. `json_write_ndjson()` writes one line for each element of a list, or each row of a data frame: ```{r} lines <- json_write_ndjson(res$items) cat(lines) ``` `json_parse_ndjson()` reads such a body back as a list with one element per line: ```{r} records <- json_parse_ndjson(lines) identical(records, res$items) ``` ## Where next zujson stops there on purpose: it has no matrices, no streaming parser and no custom serializers, and `?zujson` lists what is out of scope. - [Handle malformed or untrusted input](https://pedrobtz.github.io/zujson/articles/untrusted-input.html): the condition classes, the depth and size limits, and when validating first is not enough. - [Read a large API document](https://pedrobtz.github.io/zujson/articles/kubernetes-openapi.html): the same functions on the 3.3 MB Kubernetes API specification. - [Coming from jsonlite](https://pedrobtz.github.io/zujson/articles/jsonlite.html): where the two packages give different results for the same input. - [Testing and conformance](https://pedrobtz.github.io/zujson/articles/testing.html): how the package is checked, and what it does with the JSON that parsers disagree on. - The [reference](https://pedrobtz.github.io/zujson/reference/index.html): every function, with the full type mapping under `?json_parse` and `?json_write`.