hecate_plugin_api (hecate_sdk v0.6.2)

JSON API utilities for plugin Cowboy handlers.

Provides consistent JSON request/response handling for all plugins. Every function that sends a response automatically increments the appropriate metric counter (api_requests for all responses, api_errors for error responses).

Response format follows the hecate convention: Success: {ok: true, ...fields} Error: {ok: false, error: "reason"}

Values of undefined are sanitized to null before JSON encoding, so OTP json produces JSON null instead of the string "undefined".

Summary

Functions

bad_request(Reason, Req)

400 Bad Request.

format_error(Reason)

Format error term to binary for JSON encoding.

get_field(Key, Map)

Get field from map, supporting both atom and binary keys.

get_field(Key, Map, Default)

Get field from map with default, supporting both atom and binary keys.

json_error(StatusCode, Reason, Req)

Send an error response with {ok: false, error: reason}. Increments the api_errors metric in addition to api_requests.

json_ok(Result, Req)

Send a 200 OK response with {ok: true} merged.

json_ok(StatusCode, Result, Req)

Send OK response with custom status code and {ok: true} merged.

json_reply(StatusCode, Body, Req)

Send a JSON response (alias for json_response/3).

json_response(StatusCode, Body, Req)

Send a JSON response with status code. Increments the api_requests metric. Sanitizes undefined to null.

method_not_allowed(Req)

405 Method Not Allowed.

not_found(Req)

404 Not Found.

read_json_body(Req)

Read and decode JSON body from request.

sanitize_for_json(Map)

Recursively sanitize data for JSON encoding. Converts atom undefined to null so json:encode/1 produces JSON null instead of the string "undefined".

Functions

bad_request(Reason, Req)

-spec bad_request(Reason :: term(), Req :: cowboy_req:req()) -> {ok, cowboy_req:req(), []}.

400 Bad Request.

format_error(Reason)

-spec format_error(term()) -> binary().

Format error term to binary for JSON encoding.

get_field(Key, Map)

-spec get_field(Key :: atom(), Map :: map()) -> term().

Get field from map, supporting both atom and binary keys.

get_field(Key, Map, Default)

-spec get_field(Key :: atom(), Map :: map(), Default :: term()) -> term().

Get field from map with default, supporting both atom and binary keys.

json_error(StatusCode, Reason, Req)

-spec json_error(StatusCode :: non_neg_integer(), Reason :: term(), Req :: cowboy_req:req()) ->
                    {ok, cowboy_req:req(), []}.

Send an error response with {ok: false, error: reason}. Increments the api_errors metric in addition to api_requests.

json_ok(Result, Req)

-spec json_ok(Result :: map(), Req :: cowboy_req:req()) -> {ok, cowboy_req:req(), []}.

Send a 200 OK response with {ok: true} merged.

json_ok(StatusCode, Result, Req)

-spec json_ok(StatusCode :: non_neg_integer(), Result :: map(), Req :: cowboy_req:req()) ->
                 {ok, cowboy_req:req(), []}.

Send OK response with custom status code and {ok: true} merged.

json_reply(StatusCode, Body, Req)

-spec json_reply(StatusCode :: non_neg_integer(), Body :: map(), Req :: cowboy_req:req()) ->
                    {ok, cowboy_req:req(), []}.

Send a JSON response (alias for json_response/3).

json_response(StatusCode, Body, Req)

-spec json_response(StatusCode :: non_neg_integer(), Body :: map(), Req :: cowboy_req:req()) ->
                       {ok, cowboy_req:req(), []}.

Send a JSON response with status code. Increments the api_requests metric. Sanitizes undefined to null.

method_not_allowed(Req)

-spec method_not_allowed(Req :: cowboy_req:req()) -> {ok, cowboy_req:req(), []}.

405 Method Not Allowed.

not_found(Req)

-spec not_found(Req :: cowboy_req:req()) -> {ok, cowboy_req:req(), []}.

404 Not Found.

read_json_body(Req)

-spec read_json_body(Req :: cowboy_req:req()) ->
                        {ok, map(), cowboy_req:req()} | {error, invalid_json, cowboy_req:req()}.

Read and decode JSON body from request.

sanitize_for_json(Map)

-spec sanitize_for_json(term()) -> term().

Recursively sanitize data for JSON encoding. Converts atom undefined to null so json:encode/1 produces JSON null instead of the string "undefined".