JSON

Description

This namespace provides iRule commands to operate on the JSON content in an HTTP or HTTP/2 message body.
  • If the HTTP Content-Type is application/json the JSON is expected to occupy the entire message body.
  • If the HTTP Content-Type is multipart/related the JSON is expected in the first part which is expected to have Content-Type application/json.
When a JSON profile exists, any JSON message body is parsed into a ‘JSON cache’ before one of the JSON events described is raised, and the JSON cache may be operated on via these commands. It is also possible to parse an arbitrary string into a JSON cache and operate on that from an HTTP event. Operations include accessing, editing, and rendering the JSON cache.

Notes

  • Terminology: A JSON ‘element’ refers to a syntactic part of JSON known as a ‘value’. This term is used to distinguish the element from the more generic term ‘value’ which refers to the content of the element.
  • Literal type: JSON supports a generic ‘number’ type of value, but does not distinguish different types of numbers. The TMM only supports integers up to 64-bits for numeric processing, so this parser has an ‘integer’ type for that purpose. Other numbers are represented as a ‘literal’ type which is simply not translated to a number internally, and passed though. If accessed it is treated as a string (but without escape sequences and not surrounded by double-quotes).
  • Handles: Internal structure elements of JSON (objects, arrays, and elements) are passed in and out of various iRule commands in this namespace, as special ‘handles’ that are recognized by the commands in this namespace. They appear in Tcl as strings, but their content is meaningful only inside these commands. Handles should simply be stored and retrieved in variables.
  • Lazy parsing: For performance reasons the JSON content is only indexed on receipt, and parts are fully parsed on demand. That means these iRule commands might trigger parsing errors only when the content is accessed in the JSON_REQUEST event or later, which would not have been detected in time to raise JSON_REQUEST_ERROR. If that happens a Tcl error is raised.

Command List

  • JSON::array - group of subcommands that operate on a JSON array
  • JSON::create - creates a new, empty JSON cache instance
  • JSON::get - gets the value content of a JSON element
  • JSON::object - group of subcommands that operate on a JSON object
  • JSON::parse - parses JSON content into a JSON cache that can be manipulated using further JSON:: commands
  • JSON::render - returns a string containing a textual rendering of the JSON cache content
  • JSON::root - gets the JSON element (aka. JSON value) at the root of a JSON cache’s tree
  • JSON::set - sets a JSON element (aka. JSON value) to the given type and given content
  • JSON::type - gets the type of the given JSON element (aka. JSON value)

Event List

  • JSON_REQUEST - triggered upon successful parsing of valid JSON content in the body of an HTTP (or HTTP/2) request message
  • JSON_REQUEST_ERROR - triggered when an HTTP (or HTTP/2) request message’s body should contain JSON content but it could not be parsed
  • JSON_REQUEST_MISSING - triggered when an HTTP (or HTTP/2) request has no body or does not contain JSON content
  • JSON_RESPONSE - triggered upon successful parsing of valid JSON content in the body of an HTTP (or HTTP/2) response message
  • JSON_RESPONSE_ERROR - triggered when an HTTP (or HTTP/2) response message’s body should contain JSON content but it could not be parsed
  • JSON_RESPONSE_MISSING - triggered when an HTTP (or HTTP/2) response has no body or does not contain JSON content

Previous Next