README.md
# Hyperdrive
[](http://badge.fury.io/rb/hyperdrive) [](https://travis-ci.org/styleseek/hyperdrive) [](https://codeclimate.com/github/styleseek/hyperdrive) [](https://codeclimate.com/github/styleseek/hyperdrive) [](https://gemnasium.com/styleseek/hyperdrive)
Ruby DSL for defining self-documenting, HATEOAS™ complaint, Hypermedia endpoints.
## Installation
Add this line to your application's Gemfile:
gem 'hyperdrive'
And then execute:
$ bundle
Or install it yourself as:
$ gem install hyperdrive
## Usage
Proposed Syntax (WIP):
```ruby
# api.rb
hyperdrive do
resource(:thing) do
name 'Thing Resource'
desc 'Description of Thing Resource'
# Register the params you want to allow in POST, PUT, PATCH,
# and DELETE requests. The :id param is auto-registered
# and is allowed for all requests but only required for PUT,
# PATCH, and DELETE requests
param :name, '50 Chars or less' # params are required by default
param :start_date, 'Format: YYYY-MM-DD', required: false
param :end_date, 'Format: YYYY-MM-DD', required: false
# Filters only apply to GET, HEAD and OPTIONS requests
# Like allowed params, :id is registered by default. Requests without an ID
# should return an array of 1 or more resources (that match any filters
# applied). Unlike allowed params, filters are not required by default.
filter :start_date, 'Format: YYYY-MM-DD'
filter :end_date, 'Format: YYYY-MM-DD'
filter :parent_id, 'Parent ID of Thing', required: true
# Handle API Requests
#
# - Simply return a string to be used as the body of the response. How you generate
# that string is completely up to you.
# - Status Codes and Headers will be handled automatically.
# - Any unhandled requests will return a 405 "Method Not Supported" error
request(:get) do
# retrieve 1-N objects...
'{ ... }'
end
# Options and Head requests will be handled automatically and
# will use info from the GET request block you define, as needed.
# POST Requests should return the full object that was created during the request.
request(:post) do
# create the object...
'{ ... }'
end
# PUT Requests should return the full object that was updated during the request.
request(:put) do
# 'upsert' the object...
'{ ... }'
end
# PATCH requests should return the full object that was updated during the request.
request(:patch) do
# update the object...
'{ ... }'
end
# DELETE requests should return a simple response indicating success.
request(:delete) do
# delete the object...
'{"deleted":true}'
end
end
end
# config.ru
run Hyperdrive::Server
```
## CLI
### Generating Documentation
`$ hyperdrive docs <option> <parameter>`
__`--input` Option__
Use the `--input` option and specify a file or directory as a parameter to generate documentation for your API resources.
- `$ hyperdrive docs --input api.rb`
or
- `$ hyperdrive docs --input api`
`-in` can be used as an alias for `--input`
__`--output` Option__
You can also provide a `--output` option and specify a destination for your documentation to be created.
- `$ hyperdrive docs --input api.rb --output docs/docs.md`
`-out` can be used as an alias for `--output`
If the `--output` option is not provided the generated documentation will be written to `docs/doc.md` by default.
## Contributing
1. Fork it ( http://github.com/styleseek/hyperdrive/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 new Pull Request