Endpoint

Endpoints handle HTTP requests with type-safe request and response contracts.

Including Endpoint

struct MyEndpoint
  include Azu::Endpoint(RequestType, ResponseType)
end

Type Parameters:

• RequestType - Request contract type (must include Azu::Request)

• ResponseType - Response type (must include Azu::Response)

HTTP Method Macros

get

Define a GET endpoint.

get "/path"
get "/users/:id"
get "/search"

post

Define a POST endpoint.

post "/users"
post "/login"

put

Define a PUT endpoint.

put "/users/:id"

patch

Define a PATCH endpoint.

patch "/users/:id"

delete

Define a DELETE endpoint.

delete "/users/:id"

options

Define an OPTIONS endpoint.

options "/users"

head

Define a HEAD endpoint.

head "/users/:id"

Instance Methods

call

Handle the request. Must be implemented.

def call : ResponseType
  # Handle request and return response
end

Returns: ResponseType

params

Access route and query parameters.

def call
  id = params["id"]          # Route parameter
  page = params["page"]?     # Optional query parameter
end

Returns: Hash(String, String)

headers

Access request headers.

def call
  auth = headers["Authorization"]?
  content_type = headers["Content-Type"]?
end

Returns: HTTP::Headers

context

Access the full HTTP context.

def call
  context.request   # HTTP::Request
  context.response  # HTTP::Server::Response
end

Returns: HTTP::Server::Context

request

Access the HTTP request.

def call
  method = request.method
  path = request.path
  body = request.body
end

Returns: HTTP::Request

response

Access the HTTP response.

def call
  response.headers["X-Custom"] = "value"
  response.status_code = 201
end

Returns: HTTP::Server::Response

status

Set the response status code.

def call
  status 201  # Created
  status 204  # No Content
end

Parameters:

• code : Int32 - HTTP status code

Request Access

Access the typed request via generated method:

struct CreateUserEndpoint
  include Azu::Endpoint(CreateUserRequest, UserResponse)

  post "/users"

  def call : UserResponse
    # Access request via snake_case method name
    create_user_request.name
    create_user_request.email
  end
end

Method name is derived from request type: CreateUserRequest → create_user_request

Response Helpers

json

Return JSON response.

def call
  json({message: "Hello", count: 42})
end

text

Return plain text response.

def call
  text "Hello, World!"
end

html

Return HTML response.

def call
  html "<h1>Hello</h1>"
end

redirect_to

Redirect to another URL.

def call
  redirect_to "/dashboard"
  redirect_to "/login", status: 301  # Permanent
end

Parameters:

• url : String - Redirect URL

• status : Int32 = 302 - HTTP status code

Route Parameters

Path Parameters

get "/users/:id"
get "/users/:user_id/posts/:post_id"

def call
  user_id = params["user_id"]
  post_id = params["post_id"]
end

Wildcard Parameters

get "/files/*path"

def call
  path = params["path"]  # Captures rest of path
end

Complete Example

struct UserEndpoint
  include Azu::Endpoint(EmptyRequest, UserResponse)

  get "/users/:id"

  def call : UserResponse
    user_id = params["id"].to_i64
    user = User.find?(user_id)

    unless user
      raise Azu::Response::NotFound.new("/users/#{user_id}")
    end

    UserResponse.new(user)
  end
end

struct UserResponse
  include Azu::Response

  def initialize(@user : User)
  end

  def render
    {
      id: @user.id,
      name: @user.name,
      email: @user.email
    }.to_json
  end
end

See Also

• Request Reference

• Response Reference

• Router Reference