Liberator.Resource behaviour (liberator v1.4.0) View Source

A controller module that understands and respects the HTTP spec.

This module implements a Plug handler that allows an endpoint to comply to the HTTP specification, and to do so by just answering a few questions.

Define a simple resource like this:

defmodule MyFirstResource do
  use Liberator.Resource

  def handle_ok(_), do: "Hello world!"
end

To add this plug to a Phoenix application, use the Phoenix.Router.forward/4 keyword in your router:

scope "/", MyApp do
  pipe_through [:browser]

  forward "/api/resource", MyFirstResource
end

If you're using another Plug-based framework, use Plug.forward/4 once you've matched on the path:

defmodule Router do
 def init(opts), do: opts

 def call(conn, opts) do
   case conn do
     %{host: "localhost", path_info: ["resources" | rest]} ->
       Plug.forward(conn, rest, MyFirstResource, opts)

     _ ->
       MainRouter.call(conn, opts)
   end
 end
end

There are lots of decisions to be made during content negotiation, and Liberator lets gives you access to every single one, but it's also built with sensible defaults that let you quickly build up a controller.

Content Negotiation

These functions return lists of available values during content negotiation. If the client has an accept header that does not match a value from these lists, the plug will return a 406 Not Acceptable response, and call handle_not_acceptable/1.

Function	Default
`allowed_methods/1`	`["GET", "HEAD"]`
`known_methods/1`	`["GET", "HEAD", "OPTIONS", "PUT", "POST", "DELETE", "PATCH", "TRACE"]`
`available_media_types/1`	`["text/plain", "application/json"]`
`available_languages/1`	`["*"]`
`available_charsets/1`	`["UTF-8"]`
`available_encodings/1`	`["gzip", "deflate","identity"]`
`maximum_entity_length/1`	`64_000`

Liberator supports a few basic defaults to help you get up and running. It uses Jason for application/json media responses, but you can override that, along with the compression handlers. Just include your custom codecs in config.exs under the :liberator key. Media type codecs go under :media_types, and compression goes under :encodings. Here's the default as an example:

config :liberator,
  media_types: %{
    "text/plain" => Liberator.MediaType.TextPlain,
    "application/json" => Jason
  },
  encodings: %{
    "identity" => Liberator.Encoding.Identity,
    "deflate" => Liberator.Encoding.Deflate,
    "gzip" => Liberator.Encoding.Gzip
  }

As long as your codec module implements an encode!/1 function that accepts and returns a response body, Liberator will call it at the right place in the pipeline. Implement the Liberator.MediaType or Liberator.Encoding behaviour for some compile-time assurance that you've implemented the correct function.

defmodule MyXmlCodec do
  @behaviour Liberator.MediaType

  @impl true
  def encode!(body) do
    # your cool new functionality here
  end
end

Preconditions

These functions decide the state of preconditon decisions for the request. Depending on the specific method and request headers, the plug may return a 412 Precondition Failed response, a 304 Not Modified response, or may allow another kind of request to continue.

Function	Default
`last_modified/1`	`DateTime.utc_now()`
`etag/1`	`nil`

Actions

Actions make the necessary changes to the requested entity. You can return either a Plug.Conn struct, or a map, from these functions. However, unlike the decision functions, a nil or false return value does nothing different.

Function	Description
`initialize/1`	Performs any custom initialization you need before the decision tree starts
`delete!/1`	Called for `DELETE` requests
`patch!/1`	Called for `PATCH` requests
`post!/1`	Called for `POST` requests
`put!/1`	Called for `PUT` requests

Handlers

Handlers are called at the very end of the decision tree, and allow you to return content for rendering to the client.

Function	Status
`handle_ok/1`	200
`handle_options/1`	200
`handle_created/1`	201
`handle_accepted/1`	202
`handle_no_content/1`	204
`handle_multiple_representations/1`	300
`handle_moved_permanently/1`	301
`handle_see_other/1`	303
`handle_not_modified/1`	304
`handle_moved_temporarily/1`	307
`handle_malformed/1`	400
`handle_unauthorized/1`	401
`handle_forbidden/1`	403
`handle_not_found/1`	404
`handle_method_not_allowed/1`	405
`handle_not_acceptable/1`	406
`handle_conflict/1`	409
`handle_gone/1`	410
`handle_precondition_failed/1`	412
`handle_request_entity_too_large/1`	413
`handle_uri_too_long/1`	414
`handle_unsupported_media_type/1`	415
`handle_unprocessable_entity/1`	422
`handle_too_many_requests/1`	429
`handle_unavailable_for_legal_reasons/1`	451
`handle_unknown_method/1`	501
`handle_not_implemented/1`	501
`handle_service_unavailable/1`	503

Decisions

Liberator supports a whole lot of decisions points. Some of them are needed for next to every resource definition. Others are seldom used or there is no other sensible implementation.

Decision callbacks must return a truthy value, which they can optionally wrap in an {:ok, result} tuple. Returning {:error, result} will always invoke the handle_error; see below.

If the result of the decision is a map, Liberator will merge that map with the conn's :assigns map. Use this feature to cache data and do work when it makes sense. For example, the exists?/1 callback is a great place to fetch your resource, and you can return it as a map for your later functions to act upon. That would look something like this:

def exists?(conn) do
  id = List.last(conn.path_info)
  try do
    Hello.Blog.get_post!(id)
  rescue
    Ecto.NoResultsError -> false
    ArgumentError -> false
  else
    post -> %{post: post}
  end
end

Here are all the decision functions you can override:

Function	Description	Default
`allowed?/1`	Is the user allowed to make this request?	true
`authorized?/1`	Is necessary authentication information present?	true
`charset_available?/1`	Are any of the requested charsets available? Should assign the `:charset` variable.	Uses values at `available_charsets/1`
`can_post_to_gone?/1`	Should we process a `POST` to a resource that previously existed?	false
`can_post_to_missing?/1`	Should we process a `POST` to a resource that does not exist?	true
`can_put_to_missing?/1`	Should we process a `PUT` to a resource that does not exist?	true
`conflict?/1`	Does the `PUT` or `POST` request result in a conflict?	false
`delete_enacted?/1`	Was the delete request finally processed?	true
`encoding_available?/1`	Is the requested encoding available? Should assign the `:encoding` variable.	Uses values at `available_encodings/1`
`etag_matches_for_if_match?/1`	Does the etag of the current resource match the `If-Match` header?	Uses value generated by `etag/1`
`etag_matches_for_if_none?/1`	Does the etag of the current resource match the `If-None-Match` header?	Uses value generated by `etag/1`
`existed?/1`	Did the resource exist before?	false
`exists?/1`	Does the resource exist?	true
`known_content_type?/1`	Is the `Content-Type` of the body known?	true
`known_method?/1`	Is the request method known?	Uses values at `known_methods/1`
`language_available?/1`	Is the requested language available? Should assign the `:language` variable.	Uses values at `available_languages/1`
`media_type_available?/1`	Is the requested media type available? Should assign the `:media_type` variale.	Uses values at `available_media_types/1`
`method_allowed?/1`	Is the request method allowed for this resource?	Uses values at `allowed_methods/1`
`modified_since?/1`	Was the resource modified since the date given in the `If-Modified-Since` header?	Uses value generated by `last_modified/1`
`moved_permanently?/1`	Was the resource moved permanently?	false
`moved_temporarily?/1`	Was the resource moved temporarily?	false
`multiple_representations?/1`	Are there multiple representations for this resource?	false
`new?/1`	Was the resource created by this request?	true
`payment_required?/1`	Is payment required before this request can be processed?	false
`post_enacted?/1`	Was the `POST` request finally processed?	true
`put_enacted?/1`	Was the `PUT` request finally processed?	true
`patch_enacted?/1`	Was the `PATCH` request finally processed?	true
`post_redirect?/1`	Should the response redirect after a `POST`?	false
`put_to_different_url?/1`	Should the `PUT` request be made to a different URL?	false
`processable?/1`	Is the request body processable?	true
`too_many_requests?/1`	Has the client or user issued too many requests in a period of time?	false
`service_available?/1`	Is the service available?	true
`unavailable_for_legal_reasons?/1`	Is the resource not available, for legal reasons?	false
`uri_too_long?/1`	Is the request URI too long?	false
`valid_content_header?/1`	Is the `Content-Type` of the body valid?	true
`valid_entity_length?/1`	Is the length of the body valid?	Uses value at `maximum_entity_length/1`
`well_formed?/1`	Is the request parseable?	true

Handling Errors

There is a special handler, named handle_error/3, that is called when any decision, action, or handler function raises an error or returns {:error, result}. It functions much like an action_fallback module does in Phoenix.

The handle_error handler is called with the conn, the error that was raised, and the name of the decision, action, or handler that failed. Liberator expects this handler to call Plug.Conn.send_resp/1 or Plug.Conn.send_resp/3, unlike other handlers. This allows you to set the status and body yourself, or even use a Phoenix fallback controller.

The default implementation of handle_error works something like this:

@impl true
def handle_error(conn, _error, _failed_step) do
  send_resp(conn, 500, "Internal Server Error")
end

Debugging

For every request, Liberator builds a list of the decisions called and their answers. You can access this list with the :trace option of your use statement.

Set it to :log for a log message of the full trace.

defmodule MyFirstResource do
  use Liberator.Resource, trace: :log

  def handle_ok(_), do: "Hello world!"
end

You'll get a log message like this:

14:57:04.861 [debug] Liberator trace for request "my-very-specific-request-id" to /:

    1. initialize: nil (took 1 µs)
    2. service_available?: true (took 1 µs)
    3. known_method?: true (took 1 µs)
    4. uri_too_long?: false (took 1 µs)
    5. method_allowed?: true (took 1 µs)
    6. well_formed?: true (took 1 µs)
    7. authorized?: true (took 1 µs)
    8. allowed?: true (took 1 µs)
    9. too_many_requests?: false (took 1 µs)
    10. payment_required?: false (took 1 µs)
    11. valid_content_header?: true (took 1 µs)
    12. known_content_type?: true (took 1 µs)
    13. valid_entity_length?: true (took 1 µs)
    14. is_options?: false (took 1 µs)
    15. accept_exists?: false (took 1 µs)
    16. accept_language_exists?: false (took 1 µs)
    17. accept_charset_exists?: false (took 1 µs)
    18. accept_encoding_exists?: false (took 1 µs)
    19. processable?: true (took 1 µs)
    20. unavailable_for_legal_reasons?: false (took 1 µs)
    21. exists?: true (took 1 µs)
    22. if_match_exists?: false (took 1 µs)
    23. if_unmodified_since_exists?: false (took 1 µs)
    24. if_none_match_exists?: false (took 1 µs)
    25. if_modified_since_exists?: false (took 1 µs)
    26. method_delete?: false (took 1 µs)
    27. method_patch?: false (took 1 µs)
    28. post_to_existing?: false (took 1 µs)
    29. put_to_existing?: false (took 1 µs)
    30. multiple_representations?: false (took 1 µs)
    31. handle_ok: nil (took 3 µs)

Liberator will include the request ID set by the Plug.RequestId plug, if you have it as part of your pipeline.

Set the :trace option to :headers so you can get the trace as HTTP headers.

defmodule MyFirstResource do
  use Liberator.Resource, trace: :headers

  def handle_ok(_), do: "Hello world!"
end

This will add a header called x-liberator-trace that will show you the entire set of decisions, in the order they were made.

Lastly, Liberator is instrumented with the Telemetry library, and emits events upon the completion of every request. A Resource will emit the following events:

[:liberator, :request, :start]
[:liberator, :request, :stop]
[:liberator, :request, :exception]

All Telemetry events will contain the request ID and request path as metadata. The measurements for :start will contain a key called system_time which is derived by calling :erlang.system_time() The measurements for :stop and :exception will both contain a key called :duration, which is the duration of the request in native time units. The metadata for the :stop event will also contain the execution trace, which is a list of maps with the following keys:

:step: the name of the function that was executed, or the atoms :start or :stop
:result: the value the function returned
:timestamp: the time the function was called, as an Elixir date struct
:duration: how long the call took, in native time units

Internationalization and Localization (i18n and l10n)

During content negotiation (specifically, in the call to language_available?/1) the accept-language header is inspected, and the :language key is added to conn.assigns. This callback also sets the Gettext locale for the current process to the value it finds, using Gettext.put_locale/1. So, in your handler functions, all you need to do is make your usual gettext calls. Everything else is handled for you.

defmodule MyInternationalizedResource do
  use Liberator.Resource

  def available_languages(_): ["en", "es", "de", "fr"]
  def handle_ok(_), do: gettext("Hello world!")
end

All of the default handler messages are internationalized, but we need help with translations! If you can help with this, please submit a pull request on Liberator's GitHub page!

Advanced Overrides

Liberator tries to give you access to as much of the program as possible. Lots of the guts are open for you to play around in. You probably won't ever need to mess with this stuff, but it's there if you need it.

Overriding Decisions

These decision points are used internally by Liberator and provide reasonable defaults. Overriding is possible, but not useful in general.

Function	Description
`accept_charset_exists?/1`	Checks if header `Accept-Charset` exists.
`accept_encoding_exists?/1`	Checks if header `Accept-Encoding` exists.
`accept_exists?/1`	Checks if header `Accept` exists.
`accept_language_exists?/1`	Checks if header `Accept-Language` exists.
`body_exists?/1`	Checks if the request has a body.
`if_match_exists?/1`	Checks if header `If-Match` exists.
`if_match_star?/1`	Checks if header `If-Match` is `*`.
`if_match_star_exists_for_missing?/1`	Checks if header `If-Match` exists for a resource that does not exist.
`if_modified_since_exists?/1`	Checks if header `If-Modified-Since` exists.
`if_modified_since_valid_date?/1`	Checks if header `If-Modified-Since` is a valid HTTP date.
`if_none_match?/1`	Checks if the request method to handle failed `If-None-Match`
`if_none_match_exists?/1`	Checks if header `If-None-Match` exists.
`if_none_match_star?/1`	Checks if header `If-None-Match` is `*`.
`if_unmodified_since_exists?/1`	Checks if header `If-Unmodified-Since` exists.
`if_unmodified_since_valid_date?/1`	Checks if header `If-Unmodified-Since` is a valid HTTP date.
`is_options?/1`	Checks if the request method is `OPTIONS`
`method_delete?/1`	Checks if the request method is `DELETE`
`method_put?/1`	Checks if the request method is `PUT`
`method_patch?/1`	Checks if the request method is `PATCH`
`post_to_gone?/1`	Checks if the request method is `POST` for resources that do not exist anymore.
`post_to_existing?/1`	Checks if the request method is `POST` for resources that do exist.
`post_to_missing?/1`	Checks if the request method is `POST` for resources that do not exist.
`put_to_existing?/1`	Checks if the request method is `PUT` for a resource that exists.

Adding Decisions

Since version 1.3, you can even override the decision, handler, and action trees. To override the decision tree, add an option named :decision_tree_overrides into your use statement. The decision tree is a map of atom -> {atom, atom}, where all three atoms should be function names in the module that called use. The first element of the tuple is the next function to call if the key function returns true, and the second element of the tuple is the function to call if the function returns false. Your argument to :decision_tree_overrides will be merged into the default decision tree. For example, here's me overriding the first chunk of the decision tree so that the decision uri_too_long?/1 is completely skipped. That decisions happens right after known_method?/1, so just update that key to call the next decision instead, which is method_allowed?/1

defmodule LongUrisResource do
  use Liberator.Resource,
    decision_tree_overrides:  %{
      # instead of known_method?: {:uri_too_long?, :handle_unknown_method}
      known_method?: {:method_allowed?, :handle_unknown_method}
    }
end

Every function in the decision matrix needs an entry. If you're adding a new decision function of your own, that new decision needs to be in both a result tuple and a key. Otherwise, Liberator will throw an exception. Also note that Liberator cannot detect a cycle in your callbacks, so be careful!

Adding Handlers

To override the handler status, or add your own, add an option named :handler_status_overrides to your use statement, with a map of atom -> integer. The integers are the status codes that Liberator will set before calling the actual handler function.

If you are adding a new status code to Liberator, you'll also need to set :decision_tree_overrides in order to actually call this new handler, as well as a functions of those names defined in the module that called use. Here's an example of adding a handler for a new status code:

defmodule ResourceLikesToParty do
  use Liberator.Resource,
    decision_tree_overrides:  %{
      allowed?: {:likes_to_party?, :handle_forbidden}
      likes_to_party?: {:handle_likes_to_party, :too_many_requests?}
    },
    handler_status_overrides: %{
      handle_likes_to_party: 420
    }
  }

  def likes_to_party?(_conn), do: Enum.random([true, false])
  def handle_likes_to_party(_conn), do: "Hey come party with me sometime."
end

In this example, the likes_to_party?/1 callback is added, and if that function returns false, it will continue on with the pipeline, but if it returns true, then it will call the new handle_likes_to_party/1 callback, and set the status code to 420.

Adding Actions

Finally, you can override actions as well. The option is called :action_followup_overrides, and is a map of atom -> atom, where both atoms are functions defined in the module that called use. The first atom is the name of the handler function, like post!/1 or delete!/1. The second atom is the function that will be called immediately after the action.

Say you're implementing a WebDAV server using Liberator, and you want to add your own COPY decision, action, and handler. By overriding some internals, this is how you'd do it, and still have the power of the decision tree on your side!

defmodule WebDavResource do
  use Liberator.Resource,
    decision_tree_overrides:  %{
      method_delete?: {:delete!, :method_copy?}
      method_copy?: {:lock_token_valid?, :method_patch?}
      lock_token_valid?: {:copy!, :handle_locked}
    },
    handler_status_overrides: %{
      handle_locked: 423
    },
    action_followup_overrides: %{
      copy!: :respond_with_entity?
    }
  }

  @impl true
  def available_media_types(_), do: ["application/xml"]

  @impl true
  def allowed_methods(_), do: ["COPY"]

  @impl true
  def known_methods(_), do: ["GET", "HEAD", "OPTIONS", "PUT", "POST", "DELETE", "PATCH", "TRACE", "COPY"]

  def lock_token_valid?(conn), do: MyWebDavBackend.lock_token_valid?(conn)
  def copy!(conn), do: MyWebDavBackend.copy(conn)
  def handle_locked(_conn), do: "Resource Locked"
end

Link to this section Summary

Functions

call(conn, opts)

Callback implementation for Plug.call/2.

init(opts)

Callback implementation for Plug.init/1.

Callbacks

accept_charset_exists?(arg1)

Check if the Accept-Charset header exists.

accept_encoding_exists?(arg1)

Check if the Accept-Encoding header exists.

accept_exists?(arg1)

Check if the Accept header exists.

accept_language_exists?(arg1)

Check if the Accept-Language header exists.

allowed?(arg1)

Check the authentication information in the request to see if it has the necessary permissions.

allowed_methods(arg1)

Returns a list of HTTP methods that this module serves.

authorized?(arg1)

Check for presence ofauthentication information in the request.

available_charsets(arg1)

Returns a list of available content charsets.

available_encodings(arg1)

Returns a list of available response content encodings (AKA compressions).

available_languages(arg1)

Returns a list of available languages.

available_media_types(arg1)

Returns a list of content types that this module serves.

body_exists?(arg1)

Check if the request has a body.

can_post_to_gone?(arg1)

Decide if we can process a POST to a resource that existed before, or return a 410 Gone response.

can_post_to_missing?(arg1)

Check if we can process a post to a resource that does not exist, or if we should send a 404 Not Found response.

can_put_to_missing?(arg1)

Decide if we can PUT to a resource that does not exist, or return 501 Not Implemented.

charset_available?(arg1)

Check of the requested charset is available.

conflict?(arg1)

Does the PUT or POST request result in a conflict?

delete!(arg1)

Called for DELETE requests.

delete_enacted?(arg1)

Check if the DELETE request was processed. Return false here if the request was put on some processing queue and the delete was not actually enacted yet. Returning false here would return a 202 Accepted instead of some other response.

encoding_available?(arg1)

Check of the requested encoding is available.

etag(arg1)

Returns the etag for the current entity.

etag_matches_for_if_match?(arg1)

Check if the etag for the current resource matches the value in the If-Match header.

etag_matches_for_if_none?(arg1)

Check if the etag of the current resource matches the If-Match-None header.

existed?(arg1)

Check if the resource ever existed.

exists?(arg1)

Check if the requested entity exists.

handle_accepted(arg1)

Returns content for a 202 Accepted response.

handle_conflict(arg1)

Returns content for a 409 Conflict response.

handle_created(arg1)

Returns content for a 201 Created response.

handle_error(arg1, term, atom)

Returns a conn for a 500 Internal Server Error response.

handle_forbidden(arg1)

Returns content for a 403 Forbidden response.

handle_gone(arg1)

Returns content for a 410 Gone response.

handle_malformed(arg1)

Returns content for a 400 Malformed response.

handle_method_not_allowed(arg1)

Returns content for a 405 Method Not Allowed response.

handle_moved_permanently(arg1)

Returns content for a 301 Moved Permanently response.

handle_moved_temporarily(arg1)

Returns content for a 307 Moved Permanently response.

handle_multiple_representations(arg1)

Returns content for a 300 Multiple Representations response.

handle_no_content(arg1)

Returns content for a 204 No Content response.

handle_not_acceptable(arg1)

Returns content for a 406 Not Acceptable response.

handle_not_found(arg1)

Returns content for a 404 Not Found response.

handle_not_implemented(arg1)

Returns content for a 501 Not Implemented response.

handle_not_modified(arg1)

Returns content for a 304 Not Modified response.

handle_ok(arg1)

Returns content for a 200 OK response.

handle_options(arg1)

Returns content for a 200 OK response to an OPTIONS request.

handle_payment_required(arg1)

Returns content for a 402 Payment Required response.

handle_precondition_failed(arg1)

Returns content for a 412 Precondition Failed response.

handle_request_entity_too_large(arg1)

Returns content for a 413 Entity Too Large response.

handle_see_other(arg1)

Returns content for a 303 See Other response.

handle_service_unavailable(arg1)

Returns content for a 503 Service Unavailable response.

handle_too_many_requests(arg1)

Returns content for a 429 Too Many Requests response.

handle_unauthorized(arg1)

Returns content for a 401 Unauthorized response.

handle_unavailable_for_legal_reasons(arg1)

Returns content for a 451 Unavailable for Legal Reasons response.

handle_unknown_method(arg1)

Returns content for a 501 Unknown Method response.

handle_unprocessable_entity(arg1)

Returns content for a 422 Unprocesable Entity response.

handle_unsupported_media_type(arg1)

Returns content for a 415 Unsuppported Media Type response.

handle_uri_too_long(arg1)

Returns content for a 414 URI Too Long response.

if_match_exists?(arg1)

Check if the If-Match header exists.

if_match_star?(arg1)

Check if the If-Match header is *.

if_match_star_exists_for_missing?(arg1)

Check if the If-Match * header exists for a resource that does not exist.

if_modified_since_exists?(arg1)

Check if the If-Modified-Since header exists.

if_modified_since_valid_date?(arg1)

Check if the If-Modified-Since header is a valid HTTP date.

if_none_match?(arg1)

Check if the request method to handle failed if-none-match.

if_none_match_exists?(arg1)

Check if the If-None-Match header exists.

if_none_match_star?(arg1)

Check if the If-None-Match header is *.

if_unmodified_since_exists?(arg1)

Check if the If-Unmodified-Since header exists.

if_unmodified_since_valid_date?(arg1)

Check if the If-Unmodified-Since header is a valid HTTP date.

initialize(arg1)

A hook invoked at the beginning of the decision tree to set up anything you may need.

is_options?(arg1)

Check if the request method is Options.

known_content_type?(arg1)

Check if the Content-Type of the body is known.

known_method?(arg1)

Check of the HTTP method in the request is one we know about.

known_methods(arg1)

Returns a list of HTTP methods that exist.

language_available?(arg1)

Check if the requested language is available.

last_modified(arg1)

Returns the last modified date of your resource.

malformed?(arg1) deprecated

Check the request for general adherence to some form.

maximum_entity_length(arg1)

Configures the maximum length that a request body can be.

media_type_available?(arg1)

Check if the request media type is available.

method_allowed?(arg1)

Check if the server supports the request's HTTP method.

method_delete?(arg1)

Check if the request method is DELETE.

method_patch?(arg1)

Check if the request method is PATCH.

method_post?(arg1)

Check if the request method is POST.

method_put?(arg1)

Check if the request method is PUT.

modified_since?(arg1)

Checks if the resource was modified since the date given in the If-Modified-Since header.

moved_permanently?(arg1)

Check if the resource was moved permanently.

moved_temporarily?(arg1)

Check if the resource was moved temporarily.

multiple_representations?(arg1)

Check if there are multiple representations of the resource.

new?(arg1)

Was the resource created by this request?

patch!(arg1)

Called for PATCH requests.

patch_enacted?(arg1)

Check if the PATCH request was processed. Return false here if the request was put on some processing queue and the patch was not actually enacted yet. Returning false here would return a 202 Accepted instead of some other response.

payment_required?(arg1)

Check to see if payment is required for this resource.

post!(arg1)

Called for POST requests.

post_enacted?(arg1)

Check if the POST request was processed. Return false here if the request was put on some processing queue and the post was not actually enacted yet. Returning false here would return a 202 Accepted instead of some other response.

post_redirect?(arg1)

Decide if the response should redirect after a POST.

post_to_existing?(arg1)

Check if the request method is POST for a resource that already exists.

post_to_gone?(arg1)

Check if the request method is POST for resources that do not exist anymore.

post_to_missing?(arg1)

Check if the request method is POST to a resource that doesn't exist.

processable?(arg1)

Check if the body of the request can be processed.

put!(arg1)

Called for PUT requests.

put_enacted?(arg1)

Check if the PUT request was processed. Return false here if the request was put on some processing queue and the put was not actually enacted yet. Returning false here would return a 202 Accepted instead of some other response.

put_to_different_url?(arg1)

Decide if a PUT request should be made to a different URL.

put_to_existing?(arg1)

Check if the request method is a PUT for a resource that already exists.

respond_with_entity?(arg1)

Should the response contain a representation of the resource?

service_available?(arg1)

Check if your service is available.

too_many_requests?(arg1)

Check to see if the client has performed too many requests. Used as part of a rate limiting scheme.

unavailable_for_legal_reasons?(arg1)

Check if the resource is no longer available, for legal reasons.

unmodified_since?(arg1)

Checks if the resource was not modified since the date given in the If-Unmodified-Since header.

uri_too_long?(arg1)

Checks the length of the URI.

valid_content_header?(arg1)

Check if the Content-Type of the body is valid.

valid_entity_length?(arg1)

Check if the length of the body is valid.

well_formed?(arg1)

Check the request for general adherence to some form.

Link to this section Functions

call(conn, opts)

Callback implementation for Plug.call/2.

init(opts)

Callback implementation for Plug.init/1.

Link to this section Callbacks

accept_charset_exists?(arg1)

(since 1.0)

Specs

accept_charset_exists?(Plug.Conn.t()) :: true | false

Check if the Accept-Charset header exists.

Used internally; it is not advised to override this function.

accept_encoding_exists?(arg1)

(since 1.0)

Specs

accept_encoding_exists?(Plug.Conn.t()) :: true | false

Check if the Accept-Encoding header exists.

Used internally; it is not advised to override this function.

accept_exists?(arg1)

(since 1.0)

Specs

accept_exists?(Plug.Conn.t()) :: true | false

Check if the Accept header exists.

Used internally; it is not advised to override this function.

accept_language_exists?(arg1)

(since 1.0)

Specs

accept_language_exists?(Plug.Conn.t()) :: true | false

Check if the Accept-Language header exists.

Used internally; it is not advised to override this function.

allowed?(arg1)

(since 1.0)

Specs

allowed?(Plug.Conn.t()) :: true | false

Check the authentication information in the request to see if it has the necessary permissions.

Note the difference between authorized?/1 and allowed?/1. This function checks if the given request is allowed to perform an action, but isn't responsible for checking the presence of authentication information in the first place.

By default, always returns true.

allowed_methods(arg1)

(since 1.0)

Specs

allowed_methods(Plug.Conn.t()) :: list()

Returns a list of HTTP methods that this module serves.

The methods returned by this function should be upper-case strings, like "GET", "POST", etc.

authorized?(arg1)

(since 1.0)

Specs

authorized?(Plug.Conn.t()) :: true | false

Check for presence ofauthentication information in the request.

available_languages(Plug.Conn.t()) :: list()

Returns a list of available languages.

available_media_types(arg1)

(since 1.0)

Specs

available_media_types(Plug.Conn.t()) :: list()

Returns a list of content types that this module serves.

The types returned by this function should be valid MIME types, like text/plain, application/json, etc.

body_exists?(arg1)

Specs

body_exists?(Plug.Conn.t()) :: true | false

Check if the request has a body.

Used internally; it is not advised to override this function.

can_post_to_gone?(arg1)

(since 1.0)

Specs

can_post_to_gone?(Plug.Conn.t()) :: true | false

Decide if we can process a POST to a resource that existed before, or return a 410 Gone response.

By default, always returns false.

can_post_to_missing?(arg1)

(since 1.0)

Specs

can_post_to_missing?(Plug.Conn.t()) :: true | false

Check if we can process a post to a resource that does not exist, or if we should send a 404 Not Found response.

By default, always returns true.

can_put_to_missing?(arg1)

(since 1.0)

Specs

can_put_to_missing?(Plug.Conn.t()) :: true | false

Decide if we can PUT to a resource that does not exist, or return 501 Not Implemented.

By default, always returns true.

charset_available?(arg1)

(since 1.0)

Specs

charset_available?(Plug.Conn.t()) :: true | false

encoding_available?(Plug.Conn.t()) :: true | false

Check of the requested encoding is available.

By default, uses the values returned by available_encodings/1, and returns a map with the key :encoding set to the negotiated encoding, which will be merged into conn.assigns.

etag(arg1)

(since 1.0)

Specs

etag(Plug.Conn.t()) :: String.t()

Returns the etag for the current entity.

This value will be used to respond to caching headers like If-None-Match.

etag_matches_for_if_match?(arg1)

(since 1.0)

Specs

etag_matches_for_if_match?(Plug.Conn.t()) :: true | false

Check if the etag for the current resource matches the value in the If-Match header.

By default, checks the header against the value returned by etag/1.

etag_matches_for_if_none?(arg1)

(since 1.0)

Specs

etag_matches_for_if_none?(Plug.Conn.t()) :: true | false

Check if the etag of the current resource matches the If-Match-None header.

By default, checks the header against the value returned by etag/1.

existed?(arg1)

(since 1.0)

Specs

existed?(Plug.Conn.t()) :: true | false

Check if the resource ever existed.

Answering true here will lead you down the path that leads to responses like "Moved Permanently" and "Gone", among othes.

exists?(arg1)

(since 1.0)

Specs

exists?(Plug.Conn.t()) :: true | false

Check if the requested entity exists.

handle_error(Plug.Conn.t(), term(), atom()) :: Plug.Conn.t()

handle_payment_required(Plug.Conn.t()) :: Plug.Conn.t()

handle_too_many_requests(Plug.Conn.t()) :: Plug.Conn.t()

Returns content for a 429 Too Many Requests response.

For more information on this response type, see RFC 6585, section 4.

handle_unauthorized(arg1)

(since 1.0)

Specs

handle_unauthorized(Plug.Conn.t()) :: Plug.Conn.t()

Returns content for a 401 Unauthorized response.

handle_unavailable_for_legal_reasons(arg1)

(since 1.2)

Specs

handle_unavailable_for_legal_reasons(Plug.Conn.t()) :: Plug.Conn.t()

if_match_exists?(Plug.Conn.t()) :: true | false

Check if the If-Match header exists.

Used internally; it is not advised to override this function.

if_match_star?(arg1)

(since 1.0)

Specs

if_match_star?(Plug.Conn.t()) :: true | false

Check if the If-Match header is *.

Used internally; it is not advised to override this function.

if_match_star_exists_for_missing?(arg1)

(since 1.0)

Specs

if_match_star_exists_for_missing?(Plug.Conn.t()) :: true | false

Check if the If-Match * header exists for a resource that does not exist.

Used internally; it is not advised to override this function.

if_modified_since_exists?(arg1)

(since 1.0)

Specs

if_modified_since_exists?(Plug.Conn.t()) :: true | false

Check if the If-Modified-Since header exists.

Used internally; it is not advised to override this function.

if_modified_since_valid_date?(arg1)

(since 1.0)

Specs

if_modified_since_valid_date?(Plug.Conn.t()) :: true | false

Check if the If-Modified-Since header is a valid HTTP date.

Used internally; it is not advised to override this function.

if_none_match?(arg1)

(since 1.0)

Specs

if_none_match?(Plug.Conn.t()) :: true | false

Check if the request method to handle failed if-none-match.

Used internally; it is not advised to override this function.

if_none_match_exists?(arg1)

(since 1.0)

Specs

if_none_match_exists?(Plug.Conn.t()) :: true | false

Check if the If-None-Match header exists.

Used internally; it is not advised to override this function.

if_none_match_star?(arg1)

(since 1.0)

Specs

if_none_match_star?(Plug.Conn.t()) :: true | false

Check if the If-None-Match header is *.

Used internally; it is not advised to override this function.

if_unmodified_since_exists?(arg1)

(since 1.0)

Specs

if_unmodified_since_exists?(Plug.Conn.t()) :: true | false

Check if the If-Unmodified-Since header exists.

Used internally; it is not advised to override this function.

if_unmodified_since_valid_date?(arg1)

(since 1.0)

Specs

if_unmodified_since_valid_date?(Plug.Conn.t()) :: true | false

Check if the If-Unmodified-Since header is a valid HTTP date.

Used internally; it is not advised to override this function.

initialize(arg1)

(since 1.0)

Specs

initialize(Plug.Conn.t()) :: any()

A hook invoked at the beginning of the decision tree to set up anything you may need.

You can return a map here and it will be merged with the given conn's :assigns map.

is_options?(arg1)

(since 1.0)

Specs

is_options?(Plug.Conn.t()) :: true | false

Check if the request method is Options.

Used internally; it is not advised to override this function.

known_content_type?(arg1)

(since 1.0)

Specs

known_content_type?(Plug.Conn.t()) :: true | false

Check if the Content-Type of the body is known.

By default, always returns true.

known_method?(arg1)

(since 1.0)

Specs

known_method?(Plug.Conn.t()) :: true | false

Check of the HTTP method in the request is one we know about.

This is different from allowed_methods/1 in that this function checks to see if the given HTTP method is an HTTP method at all. You probably want to override allowed_methods/1 and not this one, unless you're extending HTTP with more verbs.

If this function returns false, then the plug will return a 501 Unknown Method response.

By default, allows the methods returned by known_methods/1.

known_methods(arg1)

(since 1.0)

Specs

known_methods(Plug.Conn.t()) :: list()

Returns a list of HTTP methods that exist.

Note that this is to filter bad HTTP requests, not to filter requests that your endpoint does not serve. You probably want to implement allowed_methods/1 instead.

The methods returned by this function should be upper-case strings, like "GET", "POST", etc.

language_available?(arg1)

(since 1.0)

Specs

language_available?(Plug.Conn.t()) :: true | false

Check if the requested language is available.

By default, uses the values returned by available_languages/1, and returns a map with the key :language set to the negotiated language, which will be merged into conn.assigns.

last_modified(arg1)

(since 1.0)

Specs

last_modified(Plug.Conn.t()) :: DateTime.t()

Returns the last modified date of your resource.

This value will be used to respond to caching headers like If-Modified-Since.

malformed?(arg1)

(since 1.0)

This callback is deprecated. Use Liberator.Resource.well_formed?/1 instead.

Specs

malformed?(Plug.Conn.t()) :: true | false

Check the request for general adherence to some form.

If this function returns true, then the plug will return a 400 Malformed response.

If you're checking the body of a request against some schema, you should override processable?/1 instead.

By default, always returns false.

maximum_entity_length(arg1)

Specs

maximum_entity_length(Plug.Conn.t()) :: non_neg_integer()

Configures the maximum length that a request body can be.

media_type_available?(arg1)

(since 1.0)

Specs

media_type_available?(Plug.Conn.t()) :: true | false

Check if the request media type is available.

By default, uses the values returned by available_media_types/1.

method_allowed?(arg1)

(since 1.0)

Specs

method_allowed?(Plug.Conn.t()) :: true | false

payment_required?(Plug.Conn.t()) :: true | false

Check to see if payment is required for this resource.

post_redirect?(Plug.Conn.t()) :: true | false

Decide if the response should redirect after a POST.

By default, always returns false.

post_to_existing?(arg1)

(since 1.0)

Specs

post_to_existing?(Plug.Conn.t()) :: true | false

Check if the request method is POST for a resource that already exists.

Used internally; it is not advised to override this function.

post_to_gone?(arg1)

(since 1.0)

Specs

post_to_gone?(Plug.Conn.t()) :: true | false

Check if the request method is POST for resources that do not exist anymore.

Used internally; it is not advised to override this function.

post_to_missing?(arg1)

(since 1.0)

Specs

post_to_missing?(Plug.Conn.t()) :: true | false

Check if the request method is POST to a resource that doesn't exist.

Used internally; it is not advised to override this function.

processable?(arg1)

(since 1.0)

Specs

processable?(Plug.Conn.t()) :: true | false

put_to_different_url?(Plug.Conn.t()) :: true | false

service_available?(Plug.Conn.t()) :: true | false

Check if your service is available.

This is the first function called in the entire pipeline, and lets you check to make sure everything works before going deeper. If this function returns false, then the plug will return a 503 Service Not Available response.

If this function returns a map containing a value called :retry_after, Liberator will put this value into a retry-after header, Some crawlers and spiders honor this value, so they will not bother you while you're down, and will continue to index your site afterward. See MDN's docs on the retry-after header for more information.

By default, always returns true.

too_many_requests?(arg1)

(since 1.2)

Specs

too_many_requests?(Plug.Conn.t()) :: true | false

Check to see if the client has performed too many requests. Used as part of a rate limiting scheme.

If you return a map containing a :retry_after key, then the response's retry-after header will be automatically set. The value of this key can be either an Elixir DateTime object, a String HTTP date, or an integer of seconds. All of these values tell the client when they can attempt their request again. Note that if you provide a String for this value, it should be formatted as an HTTP date.

If you do return map with the key :retry_after set, and its value is not a DateTime, integer, or valid String, then Liberator will raise an exception.

By default, always returns false.

unavailable_for_legal_reasons?(arg1)

(since 1.2)

Specs

unavailable_for_legal_reasons?(Plug.Conn.t()) :: true | false

Check if the resource is no longer available, for legal reasons.

If this function returns true, then the plug will return a 451 Unavailable for Legal Reasons response.

By default, always returns false.

unmodified_since?(arg1)

(since 1.0)

Specs

unmodified_since?(Plug.Conn.t()) :: true | false

Checks if the resource was not modified since the date given in the If-Unmodified-Since header.

By default, checks the header against the value returned by last_modified/1.

uri_too_long?(arg1)

(since 1.0)

Specs

uri_too_long?(Plug.Conn.t()) :: true | false

well_formed?(Plug.Conn.t()) :: true | false

Check the request for general adherence to some form.

If this function returns false, then the plug will return a 400 Malformed response.

This is a good place to parse the request body. If, for example, the body is not valid JSON, this is the function that should return false. If you're checking the body of a request against some schema, like checking if your changeset is valid, you should override processable?/1 instead.

By default, always returns true.