Apiculture improvements

[linkyndy]

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)

[luca-suriano]

I would like to git it a try and work on the Better endpoint definition point.

What do you guys think?

[linkyndy]

That's great, @luca-suriano!

I think there's still a lot of value in using apiculture, and by tackling some issues we'll make it more approachable to people. It would be good to discuss which of the above are worth working on, and make up a plan.

[luca-suriano]

Sure :) I was starting at looking at that one. I stopped because I thought was better to discuss what's best in the first place :)