Reviewing common API Editors | Hacker News Reader

Reviewing common API Editors

medium.com

68 pointsorliesaurus19 comments

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/

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://developers.facebook.com/tools/ http://products.wolframalpha.com/api/explorer.html

As well as generic Rest API Explorers: http://www.getpostman.com/

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.

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.

whats it called? is it public?

Check out Apigee SmartDocs: https://blog.apigee.com/detail/apigee_smartdocs_introducing_...

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

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

sad to see the spam indeed

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

Sorry, it's not public and I would probably get run out of town for basing it largely on jQuery and Handlebars. (It is fast though) It looks very similar to swagger.io except everything is expanded by default and I put a very basic js search capability that filters endpoints.

Cool, would love to see it if available publicly.

Check out Apigee SmartDocs: https://blog.apigee.com/detail/apigee_smartdocs_introducing_...

I agree that the editing functionality is more complicated but still contend that most startups would benefit from using an existing solution. Wether that's a service or an open-source project doesn't matter so much.

Here's an interactive API testing tool I made: https://github.com/Mashape/API-Test-Console

Not precisely what you're looking for, but Django Rest Framework [1] provides web browsable API endpoints by default. The owner of the project is also working on a counterpart for Flask (no commits in 8 months though). [2]

[1] https://github.com/tomchristie/django-rest-framework/blob/ma...

[2] https://github.com/tomchristie/flask-api

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?)

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

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

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.

Aglio is a pretty slick and simple html render tool for use with Api Blueprint: https://github.com/danielgtaylor/aglio

Reply on news.ycombinator.com