= Documentation for JSON Feature

The json feature adds support for JSON API access for all other
features that ship with Rodauth.

When this feature is used, all other features become accessible via a
JSON API.  The JSON API uses the POST method for all requests, using
the same parameter names as the features uses.  JSON API requests to
Rodauth endpoints that use a method other than POST will result in a
405 Method Not Allowed response.

Responses are returned as JSON hashes.  In case of an error, the +error+
entry is set to an error message, and the <tt>field-error</tt> entry is set to
an array containing the field name and the error message for that field.
Successful requests by default store a +success+ entry with a success
message, though that can be disabled.

The JSON response can be modified at any point by modifying the +json_response+
hash. The following example adds an {error reason}[rdoc-ref:doc/error_reasons.rdoc]
to the JSON response:

  set_error_reason do |reason|
    json_response[:error_reason] = reason
  end

The session state is managed in the rack session, so make sure that
CSRF protection is enabled. This will be the case when passing the
<tt>json: true</tt> option when loading the rodauth plugin. If you
want to only handle JSON requests, set <tt>only_json? true</tt> in
your rodauth configuration.

If you want token-based authentication sent via the Authorization
header, consider using the jwt feature.

== Auth Value Methods

json_accept_regexp :: The regexp to use to check the Accept header for JSON if +json_check_accept?+ is true.
json_check_accept? :: Whether to check the Accept header to see if the client supports JSON responses, true by default.
json_non_post_error_message :: The error message to use when a JSON non-POST request is sent.
json_not_accepted_error_message :: The error message to display if +json_check_accept?+ is true and the Accept header is present but does not match +json_request_content_type_regexp+.
json_request_content_type_regexp :: The regexp to use to recognize a request as a json request.
json_response_content_type :: The content type to set for json responses, <tt>application/json</tt> by default.
json_response_custom_error_status? :: Whether to use custom error statuses, instead of always using +json_response_error_status+, true by default, can be set to false for backwards compatibility with Rodauth 1.
json_response_error? :: Whether the current JSON response indicates an error.  By default, returns whether +json_response_error_key+ is set.
json_response_error_key :: The JSON result key containing an error message, +error+ by default.
json_response_error_status :: The HTTP status code to use for JSON error responses if not using custom error statuses, 400 by default.
json_response_field_error_key :: The JSON result key containing an field error message, <tt>field-error</tt> by default.
json_response_success_key :: The JSON result key containing a success message for successful request, if set.  +success+ by default.
non_json_request_error_message :: The error message to use when a non-JSON request is sent and +only_json?+ is set.
only_json? :: Whether to have Rodauth only allow JSON requests.  True by default if <tt>json: :only</tt> option was given when loading the plugin.  If set, rodauth endpoints will issue an error for non-JSON requests.
use_json? :: Whether to return a JSON response. By default, a JSON response is returned if +only_json?+ is true, or if the request uses a json content type.

== Auth Methods

json_request? :: Whether the current request is a JSON request, looks at the Content-Type request header by default.
json_response_body(hash) :: The body to use for JSON response.  By default just converts hash to JSON.  Can be used to reformat JSON output in arbitrary ways.