Feature Request: Additional DSL

[MarkMurphy]

I really like the DSL Amber Feng form Stripe outlined in this blog post. Would love to see this project add support for something like that, ie. required, document, etc.

eg.

class ChargeCreateMethod < AbstractAPIMethod
  required :amount, :integer
  required :card_number, :string

  document :amount, "Amount, in cents."
  document :card_number, "The card number."

  resource ChargeAPIResource

  def execute
    create_charge(amount, card_number)
  end
end

class ChargeAPIResource < AbstractAPIResource
  required :id, :string
  required :amount, :integer
  required :card_number, :string
  required :success, :boolean

  def describe_card_number
    charge.redacted_card_number
  end
end

A good UX design principle is that you should make it really hard for your users to mess up or do the wrong thing. Why not apply this toward building the API as well?

One thing that we did that I thought was really cool was a system for documenting our API. To try to address "I forgot to update the docs!" syndrome, we made it really hard to forget by putting the documentation right under the code that adds a new property.

Our documentation then auto-generates itself from these specs—for changing most things, there's no need to go dig up static HTML files.

Source: Amber Feng - Move Fast, Don't Break Your API

[taylorthurlow]

You might be interested in my fork of this project: https://github.com/taylorthurlow/interaktor

It's not production-ready but at least you might have some opinions on how I'm doing things over there.