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 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.
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.
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.
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]
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.
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.
19 comments
[ 4.2 ms ] story [ 55.9 ms ] threadOne 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?)
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/
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.
Live editing of API functionality? Much more complicated.
(top level readers: sorry about the double-post)
Here's an interactive API testing tool I made: https://github.com/Mashape/API-Test-Console
[1] https://github.com/tomchristie/django-rest-framework/blob/ma...
[2] https://github.com/tomchristie/flask-api
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/