JSON Fundamentals

JavaScript Object Notation, or JSON, is a lightweight format for storing and transporting data of most any kind. It contains "fields" of your own choosing to convey strings, numbers, boolean values, other JSON objects, and arrays of values:

{
 "temp": 34.5,
 "skies": "cloudy",
 "windy": true
}

You can learn more about using JSON and its syntax in this online tutorial.

How the Notecard works with JSON

As you work with the Notecard API, there are a few behaviors and caveats to keep in mind:

• Fields whose value is 0, 0.0, false, or "" are omitted from Notecard responses. Treat a missing field as its zero value rather than as an error. The same rule applies to the body of Notes in templated Notefiles as they arrive in Notehub. You may add "full": true to note.add requests to keep empty fields.

• Numbers with no fractional part are written without a decimal point, so a value of 34.0 comes back as 34.

• Integers greater than 2^31 or less than -2^31, while generally supported, are technically "Undefined Behavior" by the JSON specification and thus may be converted into floating point numbers by some implementations.

• Field order and surrounding whitespace are not preserved as JSON moves between services, so don't depend on either.

• Requests follow the ndjson convention of newline-delimited JSON: each request is a single line terminated by \n. A newline anywhere else truncates the request, and any other control character — including a tab — is replaced with a space before parsing, even inside a string value. Responses contain no whitespace between tokens and are terminated with \r\n.

• Notecard accepts UTF-8, including multi-byte characters and \uXXXX escape sequences, and returns strings unescaped. String length limits are counted in bytes rather than characters, though, so budget accordingly. For large or arbitrary binary data, use a binary transfer mechanism instead.