api-blueprint

The last thing that scratched this itch for me was Dredd https://github.com/apiaryio/dredd . But writing tests in markdown is not for everyone. Here are few examples of what "test files" look like https://github.com/apiaryio/api-blueprint/tree/master/exampl... I didn't use in for two years so I can't say how well it works today (it doesn't appear to be actively maintained).

Here's a summary of the discussion (RAML vs Swagger vs Apiary vs RSpec...) we had at Lonely Planet: https://lonelyplanet.atlassian.net/wiki/display/PUB/API+Spec... 5 months in, we're happy with API Blueprint. We used to use Dredd for API validation but ran into to some limitations: - Dredd does not perform any validation against the siren response beyond the first key level. For example, it does not validate if the class-name is user-events, or usr-events - Dredd does not make any difference between Action parameters and Resource parameters. Then, an action POST to create user-events will have undesired url parameters. E.G: POST /user-events?take=0&skip=2 (The apib blueprint specs allows to make this difference: https://github.com/apiaryio/api-blueprint/blob/master/exampl...) So one of our devs created a Ruby validator, https://github.com

We used to start with Aglio (https://github.com/danielgtaylor/aglio) and the API Blueprint format 1A (https://github.com/apiaryio/api-blueprint) provided by Apiary. We recently moved from Aglio to Apiary.

The spec proposal is here: https://github.com/apiaryio/api-blueprint/tree/resource-blue...

Focus on business logic of Web API, model resource's semantic states and transitions. Full specification at https://github.com/apiaryio/api-blueprint/tree/resource-blueprint