json.rdoc

doc/json.rdoc
Last Update: 2021-01-19 17:20:20 -0800

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 field-error 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 session state is managed in the rack session, so make sure that CSRF protection is enabled. This will be the case when passing the json: true option when loading the rodauth plugin. If you want to only handle JSON requests, set only_json? true 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, application/json 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_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, field-error 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 json: :only 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.