

Apiary.io – REST tools for API documentation and testing - shawndumas
http://apiary.io/blueprint

======
timdorr
Apiary is great! I used them for documenting the Tesla Model S API:
[http://docs.timdorr.apiary.io/](http://docs.timdorr.apiary.io/)

All I had to do was create a github repo and that was it:
[https://github.com/timdorr/model-s-api](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](https://github.com/timdorr/model-s-api/commit/b0669d)
Awesome guys!

------
tpetricek
I quite like what Apiary.io is doing!

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:

The description is here:
[http://fsharp.github.io/FSharp.Data/experimental/ApiaryProvi...](http://fsharp.github.io/FSharp.Data/experimental/ApiaryProvider.html)

And a larger example (running as JavaScript) is here (sorry for the poor
formatting):
[http://funscript.info/samples/moviedatabase.html](http://funscript.info/samples/moviedatabase.html)

------
adamrneary
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.

~~~
Almad
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.

~~~
adamrneary
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!).

------
kxepal
If you'd like to use something similar on Erlang, take a look on katt project:
[https://github.com/klarna/katt/blob/master/doc/example-
httpb...](https://github.com/klarna/katt/blob/master/doc/example-httpbin.apib)

~~~
andreineculau
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 :)

If you like KATT/Apiary/HTTP mockeries, keep an eye on
[https://github.com/andreineculau/hyperrest-
bin](https://github.com/andreineculau/hyperrest-bin) and
[https://github.com/klarna/katt](https://github.com/klarna/katt)

------
culo
There is [http://mashape.com](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.

------
bwaine
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.

~~~
Almad
Hi, Lukas from Apiary here.

May I ask what your use case for response replay is? Testing or debugging?

~~~
rgbrgb
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.

~~~
Almad
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").

If you are interested in this, please subscribe to
[http://support.apiary.io/forums/120125-general/suggestions/3...](http://support.apiary.io/forums/120125-general/suggestions/3096648-test-
suite-from-blueprint) and we'll let you know once it will be available for
testing.

It's now one of our three running projects and you're gonna love it ;)

------
mylorse
So this is like CFEngine, a open source configuration management system?:
[http://cfengine.com/cfengine-code-editors](http://cfengine.com/cfengine-code-
editors)

~~~
TheHippo
No. Its for creating mock HTTP API without writing any code.

------
aggronn
I'm building an internal API at my company, which wouldn't be accessible
externally. I wish this was available for me to set up locally :(

~~~
zzen
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.

~~~
aggronn
Thanks for the tip! I'll look into it.

------
nayefc
I've been using them for a few months as well. It's the most decent one out
there. Apparently they have a new blueprint coming soon.

------
esperluette
would something that's 100% OSS be smarter for people just getting started?
Swagger jumps to mind. :-)

[https://github.com/wordnik/swagger-
core/wiki/Downloads](https://github.com/wordnik/swagger-core/wiki/Downloads)

(Node inspector recently added for command-line happiness.)

~~~
Almad
Disclaimer: I work for Apiary

I'd say that just for getting started, hosted solution works better ;)

Anyways; we love OSS and we are gradually open-sourcing more and more from our
toolbelt. Parser is completely open-source (current one
[https://github.com/apiaryio/blueprint-
parser](https://github.com/apiaryio/blueprint-parser) as well as the upcoming
version
[https://github.com/apiaryio/snowcrash](https://github.com/apiaryio/snowcrash)
).

More is coming soon ;)

(But yes, if you prefer writing JSON over Markdown...)

