Apiculture Improvements

General guidelines

• short endpoints, with at most a few lines inside
• routes should be concise and straight-forward (no nesting/wildcards/etc)
• a thin sugar coating that can be applied to most Rack frameworks
• some out-of-the-box middlewares for a slightly opinionated framework

Documentation

• Document thoroughly all stuff (halt, bail, action_result + args, json etc)

Actions

• Variables passed to action_result are instance variables in the action class
• Consider using service objects instead and call them in the endpoint itself (get rid of actions)

Error handling

• out-of-the-box, should just work, with only defining a mapping between errors and status codes/messages
• door open for logging/monitoring/exception tracking

Route listing

• List all API routes with some command (maybe grouped in Rails app)

Testing

• RSpec matchers (call endpoint, call action etc.)
• Integration with testing framework (allow get/post/status/halt in the action as if it is mounted in a dummy sinatra app -- maybe treat the action as a standalone Sinatra app extension?)
• Automatic RSpec test generator?

DSL

• Better param types

  String/Integer/etc. would look nicer as :string, :integer

param :email, 'Email address of the person', String

• Better endpoint definition

  endpoint or just post/get instead of api_method

api_method :post, '/contacts'

• Better required params

  route_param/required_param are not visually distinctive. Would make :required as an argument to param (the DSL would then have param/param :required/route_param)

route_param :id, 'Subscription ID'
required_param :street_and_number, 'Street and number', String

• Better responses

  json should accept anything and make a JSON out of it (so no more json foo.to_json). We currently deal with raw_json_response/json_response/json

• Better status codes

  Automagic messages for status codes, check http://httpstatus.es

responds_with 200, 'Contact data'

• Better endpoint descriptions

  Automagic description, from verb and resource, according to some standards

• Authentication/authorization helpers

  Helpers like authenticate!/authorize! (maybe in a gem extension to apiculture). Maybe even the possibility to define an endpoint as authenticated (should return 401 otherwise)

api_method :get, '^\/transfers\/(?<id>\w+)\/(?<recipient_id>\w+)\/(?<security_hash>\w+{6})$' do |id, recipient_id, security_hash |
    bye([id, recipient_id, security_hash])
end

This now fails because the validator for route params does not understand these regexes

because literal params in a Sinatra URL are, in fact, required :-P

Something this:

routes = Alligator::V1.apiculture_stack.select{|d| d.is_a? Apiculture::ActionDefinition}
prefix = Alligator::V1.instance_variable_get(:@apiculture_mounted_at)
format = "%7s %-75s %-50s\n"
routes.each do |route|
  printf format % [route.http_verb.upcase, prefix + route.path, route.description]
end

But a little less hacky

Out of the box apiculture supports generating documentation in HTML format.

For more seamless cooperation with consumers of an API it would be nice if we can not only generate documentation in HTML format but also in the form of a swagger or openapi definition.