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 JSON response can be modified at any point by modifying the json_response
hash. The following example adds an error reason 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 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 matchjson_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 withRodauth
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,
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 ifjson: :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.