Apiary.io – REST tools for API documentation and testing

by shawndumas • 13 years ago

112 21 13 years ago

bwaine• 13 years ago

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.

Almad4• 13 years ago

Hi, Lukas from Apiary here.

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

rgbrgb• 13 years ago

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.

nayefc• 13 years ago

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.

tpetricek• 13 years ago

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

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

kxepal• 13 years ago

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

andreineculau• 13 years ago

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 and https://github.com/klarna/katt

aggronn2• 13 years ago

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• 13 years ago

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.

aggronn2• 13 years ago

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

timdorr• 13 years ago

Apiary is great! I used them for documenting the Tesla Model S API: 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

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!

adamrneary2• 13 years ago

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.

fehguy• 13 years ago

Generating a server stub was done long ago, in swagger, which is completely OSS:

https://github.com/wordnik/swagger-codegen#to-build-a-server...

And it's based on an intuitive JSON structure.

Almad4• 13 years ago

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.

adamrneary2• 13 years ago

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

culo• 13 years ago

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.

esperluette• 13 years ago

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

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

Almad4• 13 years ago

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 as well as the upcoming version https://github.com/apiaryio/snowcrash ).

More is coming soon ;)

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

mylorse• 13 years ago

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

TheHippo• 13 years ago

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

Apiary.io – REST tools for API documentation and testing

Related Stories