onyx-http
Onyx::REST
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 passed to the Onyx::REST::Server. 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:
- Onyx::REST::Router — routes the request to a proc
- Onyx::REST::CORS — Cross Origin Resource Sharing handler
- Onyx::REST::RequestID — adds ID to the request
- Rescuers — rescue unhandled errors
- Onyx::REST::Rescuers::Standard — rescues errors and logs them colorfully to a standard Crystal logger
- Loggers — log requests
- Onyx::REST::Loggers::Standard — logs requests colorfully to a standard Crystal logger
- Renderers — render responses
- Onyx::REST::Renderers::JSON — renders to JSON
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
- Fork it ( https://github.com/onyxframework/rest/fork )
- Create your feature branch (git checkout -b my-new-feature)
- Commit your changes (git commit -am 'Add some feature')
- Push to the branch (git push origin my-new-feature)
- Create a new Pull Request
Contributors
- Vlad Faust - creator and maintainer
Licensing
This software is licensed under BSD 3-Clause License.