I can't help but wonder... a person experienced enough to design a REST API wouldn't need or want to rely on said service just to mock it up. I don't see a market for Apiary.
At least in the node.js community, there are lots of tools and projects for mocking REST APIs. Why should I spend the time to sign-up and pay for Apiary, when I could already mock an API in that time instead?
> TCP dumps, Wireshark, installing local HTTP proxies… Not fun.
Developers should be able to debug the freakin' API they are supposed to be building! If someone needs Wireshark or HTTP proxies to debug their code, they are doing it very wrong.
And what if I am using a library to connect to a 3rd party service (i.e. github) and I'd like to debug my API calls?
Sure, there are cases where you have to use a proxy to see a request. I'm surprised there's a market for people who pay for that.
And for systems where the API is provided by several different apps rather than just one, it's nice to have a centralized spec for everyone to conform to. Eventually it's supposed to test your api against your spec, which would be nice.
http://docs.timdorr.apiary.io/#vehiclecommands
My biggest problem: way too much visual emphasis on 'GET' part and not enough on the actual URL. That has way more priority, to me.
Their developer documentation is kind of tricky to figure out though.
Reminds me of IO/Docs which I use actively for my own application. I like the ability to "try it yourself" though a mix of it with "here is the default response if it works, here is the response if it fails" is better for POST/PUT/DELETE routes.
Real activity, not mocks.
thanks!
Yes, it is both and yes, you can add it to your source tree through our github integration.
Our idea is to have a human-readable, human-writeable DSL to describe your API. From there, we generate both documentation, mocks, debugging proxy and tests.
You can use it to describe your existing APIs, but in my mind, our biggest value lies in conversation around API design that happens before you start implementing.
Hope this helps!
As far as the docs themselves I think I prefer the design of something like Swagger (https://developers.helloreverb.com/swagger/).
If I could host this somewhere behind my firewall, then something like this becomes a no brainer. But making me try to convince my security team to send all of my API calls and design to an external service puts a huge barrier to entry for me politically.
I love the idea to the point that I started searching for something similar that I could host inside. Even Github lets me host a copy of their software somewhere nice and corporate safe.
I wish more service providers would offer more than just 'pure SaaS' to allow for easier adoption by corporate customers.
However, as github hasn't provided this from year one, so are we. Choosing priorities is hard in startup and on-premise takes a lot of resources.
...which is what seed is for ;)
Meanwhile, you can still use our format separately from Apiary SaaS. Please take a look: http://apiblueprint.org/
I've actually been working on something similar, but more focused on library generation and like a "npm for APIs", e.g. reusable schemas. Instead of markdown I'm using something more akin to Google's Discovery Document (https://developers.google.com/discovery/v1/reference/apis#re...).
And as said -- Apiary is more about design than documentation and writing blueprint should take place before writing code. A lot of things is lost when it's the other way around.
If you check my bio, you'll see my bias toward these problems. But there are a lot more of them and a lot more variants than you give credit to.
Are you saying you'd pay for Apiary to debug HTTP requests? How did you solve this issue before? There are many open source libraries to do exactly this.
I just can't imagine a future where development tooling consists of subscription to a bunch of disparate services.
New Relic, Exceptional/Airbrake, SendGrid/Mandrill, Codeship/CircleCI, Github, etc. You can do all of those on your own, but we pay for all these services quite often. Apiary may not be your cup of tea, but I think people will pay for it.