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):

# 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

$ 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

Fork it ( http://github.com/styleseek/hyperdrive/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 new Pull Request