Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/jwoertink/kave
Kemal API Version Extension
https://github.com/jwoertink/kave
api crystal kemal
Last synced: about 2 months ago
JSON representation
Kemal API Version Extension
- Host: GitHub
- URL: https://github.com/jwoertink/kave
- Owner: jwoertink
- License: mit
- Created: 2016-11-04T19:08:22.000Z (almost 8 years ago)
- Default Branch: master
- Last Pushed: 2019-10-27T17:56:46.000Z (almost 5 years ago)
- Last Synced: 2024-06-22T00:34:10.451Z (3 months ago)
- Topics: api, crystal, kemal
- Language: Crystal
- Size: 52.7 KB
- Stars: 29
- Watchers: 3
- Forks: 4
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-crystal - kave - Kemal API Version Extension (Framework Components)
- awesome-crystal - kave - Kemal API Version Extension (Framework Components)
README
# Kave (Kemal API Version Extension) [](https://travis-ci.com/jwoertink/kave)
This shards makes it easier to version your [Kemal](http://kemalcr.com/) API
## Installation
Add this to your application's `shard.yml`:
```yaml
dependencies:
kave:
github: jwoertink/kave
```
## Usage
```crystal
require "kemal"
require "kave"
Kave.configure do |c|
# These are default config options
# c.format = :json # see Formats below
# c.auth_strategy = nil # see Auth Strategy below
# c.token_model = Kave::AuthToken # see Auth Strategy below
# c.version_strategy = :header # see Version Strategy below
end
public do
get "/" do |env|
"This is a public route"
end
end
api("v1") do
get "/" do |env|
"This is a private route only accessed through the version 1 API"
end
before_post "/check" do |env|
"This is called before POST /v1/check"
end
post "/check" do |env|
"something here"
end
end
api("v2") do
get "/" do |env|
"This is a private route only accessed through the version 2 API"
end
end
```
## Configuration Options
### Formats
The formats are how your data will be returned. By default, Kave will assume you're building a JSON API.
Kave will automatically set your response `Content-Type` to match the type of API you're building.
For now, you must handle the data conversion yourself, but eventually Kave will take care of that for you.
```crystal
# assumes format is :json
api("v1") do
get "/users/:id" do |env|
{"id" => env.params.url["id"], "name" => "jeremy"}.to_json
end
end
```
You would make a call to this route by `http://localhost:3000/v1/users/1`
Additional options later will be `:xml`, `:msgpack`, `:plain`
### Auth Strategy
If your API isn't public, then you'll probably want to add some sort of API key. By default, Kave sets the `auth_strategy` to nil, but you can use a Bearer token authorization. To use this, set the `auth_strategy` to `:bearer`, and create a class that inherits from `Kave::AuthToken`. Set the `token_model` to your custom class, and make sure that class implements the class method `locate`.
```crystal
class MyTokenModel < Kave::AuthToken
def self.locate(token : String)
token == "abc123"
end
end
Kave.configure do |c|
c.auth_strategy = :bearer
c.token_model = MyTokenModel
end
api("v1") do
get "/users/:id" do |env|
{"id" => env.params.url["id"], "name" => "jeremy"}.to_json
end
end
```
To access this route:
```text
$ curl -H "Authorization: Bearer abc123" "http://localhost:3000/v1/users/1"
```
### Version Strategy
By default, Kave will generate paths for your API by prepending the version to your route like `/v1/whatever`. This option gives you the ability to specify your routes like `/whatever` and control the version using a header. Later there may be an option like `:subdomain` to do `v1.whatever.com/whatever`.
```crystal
Kave.configure do |c|
c.version_strategy = :header
end
api("v1") do
get "/users" do |env|
[{"id" => 1, "name" => "Jeremy"}].to_json
end
end
```
To access this route:
```text
$ curl -H "Accept: application/vnd.api.v1+json" "http://localhost:3000/users"
```
**NOTE** In a previous version of Kave you were able to change this halfway through. I realized after lots of trail and error that this was going to cause a huge mess. You can't conditionally add middleware. It's either there, or it's not. I may add that back in later if I can come up with some clever way, but until people start asking for that, it's out for now.
## Development
This is going to be a work in progress for a while. If you have a better idea for how something should be implemented, please open an issue, or submit a PR.
## Contributing
1. Fork it ( https://github.com/jwoertink/kave/fork )
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Make sure all specs pass
5. Push to the branch (git push origin my-new-feature)
6. Create a new Pull Request
## Contributors
- [jwoertink(https://github.com/jwoertink) Jeremy Woertink - creator, maintainer