Thoughts on callback interface for describing resources in an hypermedia framework

fw_resource.erl

-module(fw_resource).

-type resource() :: module().
-type uri() :: string().
-type relation() :: index | self | ...
-type action() :: fetch | stream | create | replace | append | process | delete | patch | atom().
-type media_type() :: atom().
-type internal_representation() :: any().
-type request() :: ...

%% Refers to another resource representing individual elements of the collection.
-callback collection_of() -> resource().
-optional_callbacks([collection_of/0]).

-callback uri() -> uri().
-callback actions() -> #{action() => [media_type() | {form, urlencoded} | {form, multipart}]}.
-callback relations() -> #{relation() => uri()}.

%% Used for building forms for automated selection of parameters.
-callback parameters(action()) -> ...
-optional_callbacks([parameters/1]).

%% Used for building forms for application/x-www-form-urlencoded, multipart/form-data and other inputs.
-callback forms(action()) -> ...
-optional_callbacks([forms/1]).

%% Convert from/to the external representation automatically before doing the action.
%% Functions may be called more than once (for example for the stream action).
-callback serialize(media_type(), internal_representation()) -> iodata().
-callback deserialize(media_type(), binary()) -> internal_representation().
%% Optional because some media types will already be understood by the framework.
-optional_callbacks([serialize/2, deserialize/2]).

-callback exists(request()) -> boolean().

%% The rest of the callbacks are action-specific and all are optional.

-callback fetch(request()) -> ...
-optional_callback([fetch/1]).

-callback stream(request()) -> {ok, State::any()}.
-callback stream_info(Message::any(), State::any())
    -> {ok, internal_representation(), State} | stop when State::any().
-optional_callback([stream/1, stream_info/2]).

-callback append(request(), internal_representation()) -> ok.