REST API: Add debug mode

[Viper007Bond]

It'd be nice if I could toggle on JSON_PRETTY_PRINT for the REST API for use in development, just to make life easier. A new constant such as WP_DEBUG_REST_API that enables this could be useful that could do other things in the future.

Attached is an example implementation.

[johnbillion]

Fun fact: JSON_PRETTY_PRINT was only introduced in PHP 5.4.

[adamsilverstein]

@Viper007Bond I've had great luck with browser extensions for viewing JSON, such as ​JSON Viewer for Chrome, which in addition to the pretty printing, lets you collapse/expand parts of the object tree.

[Viper007Bond]

Replying to johnbillion:

Fun fact: JSON_PRETTY_PRINT was only introduced in PHP 5.4.

Yep, but we have compatibility already in place for it: #30139

Replying to adamsilverstein:

@Viper007Bond I've had great luck with browser extensions for viewing JSON, such as ​JSON Viewer for Chrome, which in addition to the pretty printing, lets you collapse/expand parts of the object tree.

A similar feature is built into Firefox Developer Edition which I use but I also use the REST API client in my code editor (PHPStorm) which sadly just displays the raw response (although I can click a few times and get it formatted). Additionally passing authorization headers and POST data can be a pain in the browser.

[swissspidy]

Previously: ​https://github.com/WP-API/WP-API/pull/835

[TimothyBlynJacobs]

Now that the WP PHP minimum is 5.6, should this be reevaluated?

Trac ticket: https://core.trac.wordpress.org/ticket/41998

[kadamwhite]

I'd be in favor of this. It would be a good convenience while developing any sort of REST application.

@TimothyBlynJacobs has proposed in the linked PR that we support a _pretty query parameter as a purely opt-in method for this, but I'd be interested in also somehow supporting @Viper007Bond's original constant-based approach. The constant matches how we are used to stepping into and out of debug mode for script minification, and it would be convenient to be able to apply this to every response on your site in the same way (i.e. using a constant) rather than having to use a PHP filter.

[kadamwhite]

@TimothyBlynJacobs What are your thoughts on the advantages of REST_JSON_ENCODE_OPTIONS over the WP_DEBUG_REST_API constant proposed in the original trac ticket?

If I am following this, to define that I want my site to JSON pretty print, I'd use this, correct?:

define( 'REST_JSON_ENCODE_OPTIONS', JSON_PRETTY_PRINT );

I don't know that I have a strong opinion on this, and admit that WP_DEBUG_REST_API achieves a little developer-facing consistency but also possibly over-implies what you're getting in exchange for setting the constant. I'd almost expect that if I say "I'm debugging the REST API" that I'd start getting telemetry or something along with my request response, which would definitely not be the case here.

Naming things is hard. I'd love a second opinion :)

[kadamwhite]

Note from WCUS contributor day: @jorbin joined the table in person to discuss my question above. He has pointed out the issues with constants where you can't override them or easily get rid of a constant once you've added support for it, so he recommended we use the parameter-only option for now. A site owner who wants to enable or disable this globally can do so with a small filter on rest_api_json_encode_options.

That said, we usually use rest_ as the prefix, not rest_api_, so let's change that for consistency. After that, this looks solid.

[TimothyBlynJacobs]

That said, we usually use rest_ as the prefix, not rest_api_, so let's change that for consistency. After that, this looks solid.

Nice catch. Updated.

For future readers, a developer could globally enable pretty printing like this.

<?php
add_filter( 'rest_json_encode_options', function ( $options ) {
        $options |= JSON_PRETTY_PRINT;

        return $options;
} );

A developer could disable pretty printing like this.

<?php
add_filter( 'rest_json_encode_options', function ( $options ) {
        $options &= ~JSON_PRETTY_PRINT;

        return $options;
} );

[kadamwhite]

In 54127:

REST API: Introduce _pretty query parameter to opt in to JSON_PRETTY_PRINT.

Add support for a "_pretty" meta-parameter on all REST controllers which instructs WordPress to return pretty-printed JSON, for better readability when inspecting endpoint responses in curl output or certain developer tools.

Introduce the "rest_json_encode_options" filter to permit site owners to control this behavior globally.

Props Viper007Bond, TimothyBlynJacobs, chrisguitarguy, johnbillion, swissspidy, adamsilverstein, danielbachhuber, rmccue.
Fixes #41998.

Committed in bb20a180

[kadamwhite]

@jorbin I apologize for omitting you from the props list, thank you for your code review and insight.