It's great for public projects because there are both comments, which allows for inline discussion, and a mock API server, which doesn't help me so much (Tesla's API implementation isn't true REST) but allows others to throw things at an endpoint without worrying about consequences.
The services they provide are really useful for developing & testing REST services, but it is also cool because the service can be used for somewhat unexpected things :-).
I have used their API from F# to create a "type provider" (a compiler plugin) that smoothly generates type information based on the blueprint, so you can program against REST service documented on Apiary with autocomplete and type checking:
It's an interesting product as a tool for documentation, but where it gets really useful is that next step (presumably to come) where the structured content is not only used to mock a server, but to actually implement the server.
I would love to do a one-click deploy to express/everyauth (for node) or app simple sinatra/warden app for the ruby folks.
Once you define the auth requirements and the API itself, there's little left beyond the boilerplate.
I imagine a simple, closed-loop solution with semantic versioning that consumes the blueprint like a config file. As we update the blueprint and bump versions, the appropriate changes would be reflected on the server. Your live environment would be naturally in sync with documentation, and it would be versioned and tested.
Such a solution entirely frees us up to focus on the app itself, which would be very cool.
We do have some prototypes, but we are yet to venture beyond scaffolding..and honestly, we are more focused to provide basic, universal tooling and let respective communities to handle their-favorite-language/framework bindings.
From what I tried, it is fairly easy to get "almost there", but the remaining 10% is dealbreaker. If too much editing constraints are placed on resulting application, it feels odd and it's easy to break them and thus diverge from original blueprint.
One possible approach is to maintain original blueprint, then say "Let us implement" and completely blueprint as "primary data source" into scaffolded application -- into module/method docstrings and start generating blueprint back from there.
However, we are yet to find something that feels unobstrusive and natural during whole development cycle. Suggestions certainly welcome.
Right on. In our particular case, we have an API that's fairly well built-out, so I would probably toy around with this on the next side project.
Rather than having a 100% there solution that's opaque, I think the cool thing would be to have an open source project that handles the boilerplate.
Then, you could fork, point to your blueprint, and deploy in minutes and then do whatever tweaking is required to cover the remaining 10% (there's always something).
Keep up the great work--I am definitely interested (and will check out swagger, as well!).
KATT's blueprint format is a strict subset of Apiary's legacy blueprint format.
Beyond that, there are few similarities. KATT's purpose is to test if the server's response conforms with the blueprint response.
Regardless, thanks for the mention :)
I've been using this little tool to produce documentation for my team. As soon as they get more intelligent response replay in I think it will be a winner.
Until then it's still a pretty damn good web service centric markdown editor.
Maybe this isn't what he's talking about but it would be really cool if there was an easy way to test your API implementation with example requests in your documentation.
This is available as closed alpha, but we working hard on extending this functionality to be actually usable (read: scenarios, because you usually need to do at least some sort of "setUp").
Nathan - we have support for private APIs (documentation is available only for authenticated users), so if you don't mind the API specs living on AWS servers, this should work.
There is http://mashape.com too. They have almost 3000 APIs, fully documented, with SDKs in Java/Android, PHP, Ruby, Python, iOS and Win8. And an interactive test console for each endpoint + real-time status and avg latency.
All I had to do was create a github repo and that was it: https://github.com/timdorr/model-s-api
It's great for public projects because there are both comments, which allows for inline discussion, and a mock API server, which doesn't help me so much (Tesla's API implementation isn't true REST) but allows others to throw things at an endpoint without worrying about consequences.
One of the devs was even willing to get involved and issued a pull request for the repo! https://github.com/timdorr/model-s-api/commit/b0669d Awesome guys!