Endpoints is a simple module that defines the resource, and allows you to access the Request object and build the Response.
Endpoints is a simple module that defines the resource, and allows you to access the Request object and build the Response.
The endpoint is the final stage of the request process Each endpoint is the location from which APIs can access the resources of your application to carry out their function.
To ensure correctness Endpoints are designed with the Request and Response pattern in mind you can think of it as input and output to a function, where the request is the input and the response is the output.
Request and Response objects are type-safe objects that can be designed by contract.
An Endpoint requires at a minimum a Request and Response Object
The endpoint gives you access to a wide rage of functions to allow you inspect the request and modify the response.
Every endpoint must define a call method that returns a Response object.
A request object encapsulates the structure of the incoming HTTP request as needed per your application, allowing you to inspect, validate and ensuring correctness. Read more about Requests
The endpoint will contain a user_request method that returns an instance of the UserRequest object.
Read more about Requests
The most basic Azu routes accept a URI and a HTTP::Handler.
Routes can be defined withing Endpoints. Having routes defined close to the class that uses it allows for code cohesiveness and readability
All HTTP verbs are available as macro methods within Endpoints.
For flexibility Azu allows you to define routes outside of Endpoints.
Method
Description
params
context
HTTP Server context. Allows access to the raw Request and Response objects
method
HTTP Request Method
header
Gets all HTTP Headers
json
Gets request body as string
cookies
Gets request cookies
content_type(type : String)
Sets the content type of the response
header(key : String, value : String)
Sets response header
redirect(to location : String, status : Int32 = 301)
Redirect requests to a new resource
cookie(cookie : HTTP::Cookie)
Sets response cookie
status(status : Int32)
Sets response status
error(message : String, status : Int32 = 400, errors = [] of String)
Renders a response error
Access request parameters from the request body, query string, path
Params, short for parameters, allow you to access data sent by the client with the request. Requests can have parameters in different places, intuitively the params can be accessed by the attribute context location:
Params can come from:
Request path (eg. /books/:id
)
Query string (eg. /books?title=Hanami
)
Request body (eg. a POST
request to /books
)
Other than Path and Query parameters, all other parameters are parsed depending on the "Content-Type" header
Params provide hash-like access to the request attributes. Since attributes can be expected in different contexts of the request such as path, body, and query, the lookup happens in the following order of precedence.
Form
Path
Query
To access the value of a param, we can use the subscriber operator #[]
.
Given an Endpoint with a path of "/users/:id"
If we visit /users/john
, we should see path string:
john
.
If you're writing a web service application, you might find yourself more comfortable accepting parameters in JSON format. If the "Content-Type" header of your request is set to "application/json", will automatically be loaded into the params.json
object.
So for example, if you are sending this JSON content:
The params object will contain a string with the content of the JSON.
Note: Azu does not convert the params.json string into a JSON ANY object, and instead the developer can decide how to best parse.
Responses is mostly an Azu implementation detail to enable more type-safe definitions.
Response is mostly an Azu implementation detail to enable more type-safe definitions, and it does not represent the raw response from the HTTP::Server::Response. Instead responses are plain simple crystal objects that allows for easy implementation, validation and test-ability.
Azu::Responses main job is to render the body of the responses to be sent back to browsers and API clients.
Responses are created by including the Azu::Response and defining a render method that contains the body for the HTTP response.
Because of the simplicity of the module it is easy to create type safe responses, that can be validated and easily tested.
For example, lets say we want to render an IndexPage for a dashboard, we want to make ensure that a title is always provided in order to display the page.
Responses are simple Crystal classes that includes the Azu::Response module, there is no magic or macro needed, simply follows crystal conventions.
Rendering Inline HTML
Azu provides a Markup module to allow you write HTML in plain crystal
Taking the example IndexPage above we can represent the H1 using Markup DSL
Rendering Templates
Azu::Response main job is to render the body of the responses to be sent back to browsers and API clients. Most of the time, we use templates to build said responses.
Templates work great for many reasons, some of those, easy to share with designers and front-end developers, portable across teams, and clear separation from presentation and back-end code.
To use templates include the Templates::Renderable module and use the render/2 method
Requests are designed by contract in order to enforce correctness and type-safe definitions
Every HTTP request message has a specific form:
An HTTP message is either a request from a client to a server or a response from a server to a client.
Requests are designed by contract in order to enforce correctness. What this means is that requests are strictly typed and can have preconditions. With this concept.
The Request provides concise, type-safe, and self-validated request objects.
Self-documented request objects.
Type-safe requests and parameters
Enables Focused and effective testing.
JSON body requests render object instances.
Azu::Contract are provided by tight integration with the Schema shard
Example Use:
Requests can be initialized are initialized in the background and property is available to the Endpoint of the same name of the request as the camel case.
Requests can be initialized from JSON, YAML, and the standard initializes method new.
When the built-in validation helpers are not enough for your needs, you can write your own validators or validation methods as you prefer.
Custom validators are simple classes that inherit from Schema::Validator
. These classes must implement the valid?
method which takes a record as an argument and performs the validation on it. The custom validator is called using the valid?
or validate!
method.
To enable the custom validator to your structs or classes by simply defining the use ConfirmPasswordValidator
Instance Method
Description
validate
A macro to define validation rules for your request
valid?
Validates the request object and returns true or false
validate!
Validates and raises an exception when invalid
rules
returns a list of rules to be applied on validation
params
Request params. See Params
to_json
A JSON representation of the request
to_yaml
A YAML representation of the request