

Reviewing common API Editors - orliesaurus
https://medium.com/@orliesaurus/a-review-of-all-most-common-api-editors-6a720dc4f4e6

======
chatmasta
Apiarry is great. Almost all of their technology is open source, which is
ironic because they almost shot themselves in the foot by releasing their core
product source. See API Blueprint. [1].

Api blueprint is a great project with a nice ecosystem and tooling around it.
You can write the "blueprint" in your editor, serve a mock server, and run
regression tests against it, all open source on your own computer. It's easy
to setup.

This enables a workflow of "API driven development," where the first milestone
is an API blueprint, and then backend engineers can work in parallel with
frontend engineers. It can significantly cut development time, especially if
you're staffing freelancers. You know the system components will work together
because the frontend builds against a mock server, and the backend tests
against it.

[1] [http://apiblueprint.org/](http://apiblueprint.org/)

------
bvanvugt
Awesome - what about using API Editors (or similar tools) as a way to browse
or explore an API?

I've seen a lot of companies roll their own API "Explorers" too:
[https://dev.twitter.com/rest/tools/console](https://dev.twitter.com/rest/tools/console)
[https://developers.facebook.com/tools/](https://developers.facebook.com/tools/)
[http://products.wolframalpha.com/api/explorer.html](http://products.wolframalpha.com/api/explorer.html)

As well as generic Rest API Explorers:
[http://www.getpostman.com/](http://www.getpostman.com/)

~~~
anonfunction
I regularly use interactive API documentation to test APIs. It's just so much
easier than using cURL or writing a script.

Most startups can't afford to spend the time and engineering resource
reinventing the wheel for API documentation, especially with the "explorer" or
interactive test consoles that have become so popular.

~~~
altcognito
As someone who wrote one recently, it's not so hard to build the interactive
testing portion as the live editing functionality. I built an API
documentation site over a week's period with interactive consoles and
examples. (We use WADL as opposed to Swagger or others due to legacy reasons)

Live editing of API functionality? Much more complicated.

~~~
orliesaurus
whats it called? is it public?

~~~
illicium
Check out Apigee SmartDocs:
[https://blog.apigee.com/detail/apigee_smartdocs_introducing_...](https://blog.apigee.com/detail/apigee_smartdocs_introducing_smarter_api_documentation)

(top level readers: sorry about the double-post)

~~~
anonfunction
Why the apigee links? We want to see what this guy built over a week.

~~~
illicium
I was assuming you or others wanted something you could actually use today.

------
gkoberger
ReadMe founder here. Thanks for including us! Your analysis of ReadMe in the
areas you covered was spot-on; API flexibility is definitely a weak spot for
us currently. We left it intentionally slim on features during launch to see
how people used it. Over the next few weeks, we'll be rolling out huge
improvements to the API stuff. (Side note: You wouldn't believe how different
every single API is. It's crazy.)

One thing you missed was the ability/ease of non-reference guides. No matter
how good your API reference is, it's like handing someone a dictionary and
telling them to learn English. Topical guides, tutorials, and more are
insanely important.

(I'll be at Mashape tonight – see you there?)

~~~
orliesaurus
Thanks for leaving your feedback and comments. See you here, drinks on us.

~~~
fosk
Mashape is at 500 Montgomery Street in San Francisco, if you HN guys want to
join us for drinks tonight ;-)

------
jefftratner
Apiary is quite slick and easy to pick up, but I really wish they included
some kind of version control with their editor. We have a team working on our
API but it makes it harder to collaborate when we can't go back to a previous
version or see the revision history. Github integration is a no-go because we
have to give access to all repos.

------
butner
Aglio is a pretty slick and simple html render tool for use with Api
Blueprint:
[https://github.com/danielgtaylor/aglio](https://github.com/danielgtaylor/aglio)

