onyx-http

REST API framework with type-safe params and separate business and rendering layers, based on onyx-http web framework router websockets modular http-handler onyxframework
0.5.0-beta.1 released
onyxframework/http
141 11 7
Onyx Framework

Onyx::REST

Built with Crystal Travis CI build API docs Latest release

A REST API framework for Crystal.

About

Onyx::REST is an opinionated REST API framework — basically, a collection of HTTP handlers and a default HTTP::Server wrapper. It's thoroughly designed to be as much beginner-friendly as possible, yet scale with the developer's knowledge of the Crystal Language. The framework itself is modular and respects configuration over convention.

Installation

Add this to your application's shard.yml:

dependencies:
  onyx-rest:
    github: onyxframework/rest
    version: ~> 0.5.0

This shard follows Semantic Versioning v2.0.0, so check releases and change the version accordingly.

Usage

This is the most basic example of an application written with Onyx::REST:

require "onyx-rest"

router = Onyx::REST::Router.new do
  get "/" do
    "Hello Onyx!"
  end
end

server = Onyx::REST::Server.new(router)
server.bind_tcp(5000)
server.listen
INFO [14:04:31.493] ⬛ Onyx::REST::Server is listening at http://127.0.0.1:5000
INFO [14:04:32.578]      GET / 200 127μs
INFO [14:04:34.082] ⬛ Onyx::REST::Server is shutting down!
$ curl http://localhost:5000
Hello Onyx!

Handlers

Fundamentally, every Onyx::REST application is a stack of HTTP handlers. To add new functionality, you add new handlers to the stack. There is a number of implemented handlers which fit the most common REST application needs:

REST error

There is a Onyx::REST::Error abstract class which defines an expected error, for example:

class UserNotFound < Onyx::REST::Error(404)
  def initialize(id)
    super("User not found with id #{id}")
  end
end

router.get "/users/:id" do |env|
  id = env.request.path_params["id"].to_i?
  raise UserNotFound.new(id) unless Models::User.find(id)
end

You can then add a Rescuer to the stack, for example Onyx::REST::Rescuers::Standard:

handlers << Onyx::REST::Rescuers::Standard.new
$ curl http://localhost:5000/users/42
404 User not found with id 42

Params

Onyx::REST has a built-in rescuer for HTTP::Params::Serializable, which makes defining typed params a piece of cake:

require "onyx-rest"
require "onyx-rest/ext/http-params-serializable"

struct FindUserParams
  include HTTP::Params::Serializable

  getter name : String
  getter age : Int32
end

router.get "/users" do |env|
  params = FindUserParams.new(env.request.query)
  users = Models::Users.find(name: params.name, age: params.age)

  if user = users[0]?
    "#{user.first_name} #{user.last_name}"
  end
end

handlers << HTTP::Params::Serializable::Rescuer.new
$ curl http://localhost:5000/users?age=foo
400 Parameter "age" can't be cast from "foo" to Int32
$ curl http://localhost:5000/users?age=22
Vlad Faust

Contributing

  1. Fork it ( https://github.com/onyxframework/rest/fork )
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request

Contributors

Licensing

This software is licensed under BSD 3-Clause License with "Commons Clause" License Condition v1.0. See LICENSE.

onyx-http:
  github: onyxframework/http
  version: ~> 0.5.0-beta.1
Crystal 0.27.0

Authors

Dependencies 2

  • radix ~> 0.3.8
    {'github' => 'luislavena/radix', 'version' => '~> 0.3.8'}
  • time_format ~> 0.1.0
    {'github' => 'vladfaust/time_format.cr', 'version' => '~> 0.1.0'}

Development Dependencies 1

Dependents 2

Last synced .
search fire star recently