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
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.
Source: Amber Feng - Move Fast, Don't Break Your API