Liberator.Resource behaviour (liberator v1.0.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 available_media_types(_), do: ["text/plain"]
  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.

FunctionDefault
allowed_methods/1["GET", "HEAD"]
known_methods/1["GET", "HEAD", "OPTIONS", "PUT", "POST", "DELETE", "PATCH", "TRACE"]
available_media_types/1[]
available_languages/1["*"]
available_charsets/1["UTF-8"]
available_encodings/1["identity"]

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.

FunctionDefault
last_modified/1DateTime.utc_now()
etag/1nil

Actions

Actions make the necessary changes to the requested entity.

FunctionDescription
initialize/1Performs any custom initialization you need before the decision tree starts
delete!/1Called for DELETE requests
patch!/1Called for PATCH requests
post!/1Called for POST requests
put!/1Called 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.

FunctionStatus
handle_ok/1200
handle_options/1200
handle_created/1201
handle_accepted/1202
handle_no_content/1204
handle_multiple_representations/1300
handle_moved_permanently/1301
handle_see_other/1303
handle_not_modified/1304
handle_moved_temporarily/1307
handle_malformed/1400
handle_unauthorized/1401
handle_forbidden/1403
handle_not_found/1404
handle_method_not_allowed/1405
handle_not_acceptable/1406
handle_conflict/1409
handle_gone/1410
handle_precondition_failed/1412
handle_request_entity_too_large/1413
handle_uri_too_long/1414
handle_unsupported_media_type/1415
handle_unprocessable_entity/1422
handle_unknown_method/1501
handle_not_implemented/1501
handle_service_unavailable/1503

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.

Return any truthy value for a true response. If you return a map, Liberator will merge that map with the conn's :assigns map, allowing you 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.

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

Internal Decision Points

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

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

Link to this section Summary

Functions

Callback implementation for Plug.call/2.

Callback implementation for Plug.init/1.

Callbacks

Check if the Accept-Charset header exists.

Check if the Accept-Encoding header exists.

Check if the Accept header exists.

Check if the Accept-Language header exists.

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

Returns a list of HTTP methods that this module serves.

Check for presence ofauthentication information in the request.

Returns a list of available content charsets.

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

Returns a list of available languages.

Returns a list of content types that this module serves.

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

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

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

Check of the requested charset is available.

Does the PUT or POST request result in a conflict?

Called for DELETE requests.

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.

Check of the requested encoding is available.

Returns the etag for the current entity.

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

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

Check if the resource ever existed.

Check if the requested entity exists.

Returns content for a 202 Accepted response.

Returns content for a 409 Conflict response.

Returns content for a 201 Created response.

Returns content for a 403 Forbidden response.

Returns content for a 410 Gone response.

Returns content for a 400 Malformed response.

Returns content for a 405 Method Not Allowed response.

Returns content for a 301 Moved Permanently response.

Returns content for a 307 Moved Permanently response.

Returns content for a 300 Multiple Representations response.

Returns content for a 204 No Content response.

Returns content for a 406 Not Acceptable response.

Returns content for a 404 Not Found response.

Returns content for a 501 Not Implemented response.

Returns content for a 304 Not Modified response.

Returns content for a 200 OK response.

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

Returns content for a 412 Precondition Failed response.

Returns content for a 413 Entity Too Large response.

Returns content for a 303 See Other response.

Returns content for a 503 Service Unavailable response.

Returns content for a 401 Unauthorized response.

Returns content for a 501 Unknown Method response.

Returns content for a 422 Unprocesable Entity response.

Returns content for a 415 Unsuppported Media Type response.

Returns content for a 414 URI Too Long response.

Check if the If-Match header exists.

Check if the If-Match header is *.

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

Check if the If-Modified-Since header exists.

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

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

Check if the If-None-Match header exists.

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

Check if the If-Unmodified-Since header exists.

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

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

Check if the request method is Options.

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

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

Returns a list of HTTP methods that exist.

Check if the requested language is available.

Returns the last modified date of your resource.

Check the request for general adherence to some form.

Check if the request media type is available.

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

Check if the request method is DELETE.

Check if the request method is PATCH.

Check if the request method is POST.

Check if the request method is PUT.

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

Check if the resource was moved permanently.

Check if the resource was moved temporarily.

Check if there are multiple representations of the resource.

Was the resource created by this request?

Called for PATCH requests.

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.

Called for POST requests.

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.

Decide if the response should redirect after a POST.

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

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

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

Check if the body of the request can be processed.

Called for PUT requests.

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.

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

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

Should the response contain a representation of the resource?

Check if your service is available.

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

Checks the length of the URI.

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

Check if the length of the body is valid.

Link to this section Functions

Callback implementation for Plug.call/2.

Callback implementation for Plug.init/1.

Link to this section Callbacks

Link to this callback

accept_charset_exists?(arg1)

View Source (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.

Link to this callback

accept_encoding_exists?(arg1)

View Source (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.

Link to this callback

accept_exists?(arg1)

View Source (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.

Link to this callback

accept_language_exists?(arg1)

View Source (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.

Link to this callback

allowed?(arg1)

View Source (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.

Link to this callback

allowed_methods(arg1)

View Source (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.

Link to this callback

authorized?(arg1)

View Source (since 1.0)

Specs

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

Check for presence ofauthentication information in the request.

Note the difference between authorized?/1 and allowed?/1. This function should just check for the presence of authentication information, not the content of it.

If you implement this function to return false, your response in handle_unauthorized must include a WWW-Authenticate header field containing a challenge applicable to the requested resource.

By default, always returns true.

Link to this callback

available_charsets(arg1)

View Source (since 1.0)

Specs

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

Returns a list of available content charsets.

By default, only UTF-8 is supported.

Link to this callback

available_encodings(arg1)

View Source (since 1.0)

Specs

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

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

By default, only identity (no compression) is supported.

Link to this callback

available_languages(arg1)

View Source (since 1.0)

Specs

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

Returns a list of available languages.

Link to this callback

available_media_types(arg1)

View Source (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.

Link to this callback

can_post_to_gone?(arg1)

View Source (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.

Link to this callback

can_post_to_missing?(arg1)

View Source (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.

Link to this callback

can_put_to_missing?(arg1)

View Source (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.

Link to this callback

charset_available?(arg1)

View Source (since 1.0)

Specs

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

Check of the requested charset is available.

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

Link to this callback

conflict?(arg1)

View Source (since 1.0)

Specs

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

Does the PUT or POST request result in a conflict?

Link to this callback

delete!(arg1)

View Source (since 1.0)

Specs

delete!(Plug.Conn.t()) :: any()

Called for DELETE requests.

Link to this callback

delete_enacted?(arg1)

View Source (since 1.0)

Specs

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

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.

By default, always returns true.

Link to this callback

encoding_available?(arg1)

View Source (since 1.0)

Specs

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

Check of the requested encoding is available.

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

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.

Link to this callback

etag_matches_for_if_match?(arg1)

View Source (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.

Link to this callback

etag_matches_for_if_none?(arg1)

View Source (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.

Link to this callback

existed?(arg1)

View Source (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.

Link to this callback

exists?(arg1)

View Source (since 1.0)

Specs

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

Check if the requested entity exists.

This is a great place to actually fetch the requested resource, then return it as a map so it can be merged into the :assigns map of the request.

Returning false here will cause the plug to return a 404 Not Found response.

Link to this callback

handle_accepted(arg1)

View Source (since 1.0)

Specs

handle_accepted(Plug.Conn.t()) :: Plug.Conn.t()

Returns content for a 202 Accepted response.

Link to this callback

handle_conflict(arg1)

View Source (since 1.0)

Specs

handle_conflict(Plug.Conn.t()) :: Plug.Conn.t()

Returns content for a 409 Conflict response.

Link to this callback

handle_created(arg1)

View Source (since 1.0)

Specs

handle_created(Plug.Conn.t()) :: Plug.Conn.t()

Returns content for a 201 Created response.

Link to this callback

handle_forbidden(arg1)

View Source (since 1.0)

Specs

handle_forbidden(Plug.Conn.t()) :: Plug.Conn.t()

Returns content for a 403 Forbidden response.

Link to this callback

handle_gone(arg1)

View Source (since 1.0)

Specs

handle_gone(Plug.Conn.t()) :: Plug.Conn.t()

Returns content for a 410 Gone response.

Link to this callback

handle_malformed(arg1)

View Source (since 1.0)

Specs

handle_malformed(Plug.Conn.t()) :: Plug.Conn.t()

Returns content for a 400 Malformed response.

Link to this callback

handle_method_not_allowed(arg1)

View Source (since 1.0)

Specs

handle_method_not_allowed(Plug.Conn.t()) :: Plug.Conn.t()

Returns content for a 405 Method Not Allowed response.

Link to this callback

handle_moved_permanently(arg1)

View Source (since 1.0)

Specs

handle_moved_permanently(Plug.Conn.t()) :: Plug.Conn.t()

Returns content for a 301 Moved Permanently response.

Link to this callback

handle_moved_temporarily(arg1)

View Source (since 1.0)

Specs

handle_moved_temporarily(Plug.Conn.t()) :: Plug.Conn.t()

Returns content for a 307 Moved Permanently response.

Link to this callback

handle_multiple_representations(arg1)

View Source (since 1.0)

Specs

handle_multiple_representations(Plug.Conn.t()) :: Plug.Conn.t()

Returns content for a 300 Multiple Representations response.

Link to this callback

handle_no_content(arg1)

View Source (since 1.0)

Specs

handle_no_content(Plug.Conn.t()) :: Plug.Conn.t()

Returns content for a 204 No Content response.

Link to this callback

handle_not_acceptable(arg1)

View Source (since 1.0)

Specs

handle_not_acceptable(Plug.Conn.t()) :: Plug.Conn.t()

Returns content for a 406 Not Acceptable response.

Link to this callback

handle_not_found(arg1)

View Source (since 1.0)

Specs

handle_not_found(Plug.Conn.t()) :: Plug.Conn.t()

Returns content for a 404 Not Found response.

Link to this callback

handle_not_implemented(arg1)

View Source (since 1.0)

Specs

handle_not_implemented(Plug.Conn.t()) :: Plug.Conn.t()

Returns content for a 501 Not Implemented response.

Link to this callback

handle_not_modified(arg1)

View Source (since 1.0)

Specs

handle_not_modified(Plug.Conn.t()) :: Plug.Conn.t()

Returns content for a 304 Not Modified response.

Link to this callback

handle_ok(arg1)

View Source (since 1.0)

Specs

handle_ok(Plug.Conn.t()) :: Plug.Conn.t()

Returns content for a 200 OK response.

Link to this callback

handle_options(arg1)

View Source (since 1.0)

Specs

handle_options(Plug.Conn.t()) :: Plug.Conn.t()

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

Link to this callback

handle_precondition_failed(arg1)

View Source (since 1.0)

Specs

handle_precondition_failed(Plug.Conn.t()) :: Plug.Conn.t()

Returns content for a 412 Precondition Failed response.

Link to this callback

handle_request_entity_too_large(arg1)

View Source (since 1.0)

Specs

handle_request_entity_too_large(Plug.Conn.t()) :: Plug.Conn.t()

Returns content for a 413 Entity Too Large response.

Link to this callback

handle_see_other(arg1)

View Source (since 1.0)

Specs

handle_see_other(Plug.Conn.t()) :: Plug.Conn.t()

Returns content for a 303 See Other response.

Link to this callback

handle_service_unavailable(arg1)

View Source (since 1.0)

Specs

handle_service_unavailable(Plug.Conn.t()) :: Plug.Conn.t()

Returns content for a 503 Service Unavailable response.

Link to this callback

handle_unauthorized(arg1)

View Source (since 1.0)

Specs

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

Returns content for a 401 Unauthorized response.

Link to this callback

handle_unknown_method(arg1)

View Source (since 1.0)

Specs

handle_unknown_method(Plug.Conn.t()) :: Plug.Conn.t()

Returns content for a 501 Unknown Method response.

Link to this callback

handle_unprocessable_entity(arg1)

View Source (since 1.0)

Specs

handle_unprocessable_entity(Plug.Conn.t()) :: Plug.Conn.t()

Returns content for a 422 Unprocesable Entity response.

Link to this callback

handle_unsupported_media_type(arg1)

View Source (since 1.0)

Specs

handle_unsupported_media_type(Plug.Conn.t()) :: Plug.Conn.t()

Returns content for a 415 Unsuppported Media Type response.

Link to this callback

handle_uri_too_long(arg1)

View Source (since 1.0)

Specs

handle_uri_too_long(Plug.Conn.t()) :: Plug.Conn.t()

Returns content for a 414 URI Too Long response.

Link to this callback

if_match_exists?(arg1)

View Source (since 1.0)

Specs

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.

Link to this callback

if_match_star?(arg1)

View Source (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.

Link to this callback

if_match_star_exists_for_missing?(arg1)

View Source (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.

Link to this callback

if_modified_since_exists?(arg1)

View Source (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.

Link to this callback

if_modified_since_valid_date?(arg1)

View Source (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.

Link to this callback

if_none_match?(arg1)

View Source (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.

Link to this callback

if_none_match_exists?(arg1)

View Source (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.

Link to this callback

if_none_match_star?(arg1)

View Source (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.

Link to this callback

if_unmodified_since_exists?(arg1)

View Source (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.

Link to this callback

if_unmodified_since_valid_date?(arg1)

View Source (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.

Link to this callback

initialize(arg1)

View Source (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.

Link to this callback

is_options?(arg1)

View Source (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.

Link to this callback

known_content_type?(arg1)

View Source (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.

Link to this callback

known_method?(arg1)

View Source (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.

Link to this callback

known_methods(arg1)

View Source (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.

Link to this callback

language_available?(arg1)

View Source (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.

Link to this callback

last_modified(arg1)

View Source (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.

Link to this callback

malformed?(arg1)

View Source (since 1.0)

Specs

malformed?(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.

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

By default, always returns false.

Link to this callback

media_type_available?(arg1)

View Source (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.

Link to this callback

method_allowed?(arg1)

View Source (since 1.0)

Specs

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

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

Override allowed_methods/1 instead of this function to let this plug perform the check for you.

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

Link to this callback

method_delete?(arg1)

View Source (since 1.0)

Specs

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

Check if the request method is DELETE.

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

Link to this callback

method_patch?(arg1)

View Source (since 1.0)

Specs

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

Check if the request method is PATCH.

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

Link to this callback

method_post?(arg1)

View Source (since 1.0)

Specs

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

Check if the request method is POST.

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

Link to this callback

method_put?(arg1)

View Source (since 1.0)

Specs

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

Check if the request method is PUT.

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

Link to this callback

modified_since?(arg1)

View Source (since 1.0)

Specs

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

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

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

Link to this callback

moved_permanently?(arg1)

View Source (since 1.0)

Specs

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

Check if the resource was moved permanently.

By default, always returns false.

Link to this callback

moved_temporarily?(arg1)

View Source (since 1.0)

Specs

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

Check if the resource was moved temporarily.

By default, always returns false.

Link to this callback

multiple_representations?(arg1)

View Source (since 1.0)

Specs

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

Check if there are multiple representations of the resource.

Specs

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

Was the resource created by this request?

Link to this callback

patch!(arg1)

View Source (since 1.0)

Specs

patch!(Plug.Conn.t()) :: any()

Called for PATCH requests.

Link to this callback

patch_enacted?(arg1)

View Source (since 1.0)

Specs

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

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.

By default, always returns true.

Specs

post!(Plug.Conn.t()) :: any()

Called for POST requests.

Link to this callback

post_enacted?(arg1)

View Source (since 1.0)

Specs

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

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.

By default, always returns true.

Link to this callback

post_redirect?(arg1)

View Source (since 1.0)

Specs

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

Decide if the response should redirect after a POST.

By default, always returns false.

Link to this callback

post_to_existing?(arg1)

View Source (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.

Link to this callback

post_to_gone?(arg1)

View Source (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.

Link to this callback

post_to_missing?(arg1)

View Source (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.

Link to this callback

processable?(arg1)

View Source (since 1.0)

Specs

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

Check if the body of the request can be processed.

This is a good place to parse a JSON body if that's what you're doing. Returning false here would cause the plug to return a 422 Unprocessable response.

Specs

put!(Plug.Conn.t()) :: any()

Called for PUT requests.

Link to this callback

put_enacted?(arg1)

View Source (since 1.0)

Specs

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

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.

By default, always returns true.

Link to this callback

put_to_different_url?(arg1)

View Source (since 1.0)

Specs

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

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

By default, always returns false.

Link to this callback

put_to_existing?(arg1)

View Source (since 1.0)

Specs

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

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

Link to this callback

respond_with_entity?(arg1)

View Source (since 1.0)

Specs

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

Should the response contain a representation of the resource?

Link to this callback

service_available?(arg1)

View Source (since 1.0)

Specs

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.

By default, always returns true.

Link to this callback

unmodified_since?(arg1)

View Source (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.

Link to this callback

uri_too_long?(arg1)

View Source (since 1.0)

Specs

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

Checks the length of the URI.

If this function returns true, then the plug will return a 414 URI Too Long response.

By default, always returns false.

Link to this callback

valid_content_header?(arg1)

View Source (since 1.0)

Specs

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

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

By default, always returns true.

Link to this callback

valid_entity_length?(arg1)

View Source (since 1.0)

Specs

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

Check if the length of the body is valid.

By default, always returns true.