5 ms·

Reviewing common API Editors

68 points by orliesaurus 12y ago

gkoberger 12y ago
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 12y ago
  Thanks for leaving your feedback and comments. See you here, drinks on us.
  - fosk 12y ago
    Mashape is at 500 Montgomery Street in San Francisco, if you HN guys want to join us for drinks tonight ;-)
bvanvugt 12y ago
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 12y ago
  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 12y ago
    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 12y ago
      whats it called? is it public?
      - illicium 12y ago
        Check out Apigee SmartDocs: https://blog.apigee.com/detail/apigee_smartdocs_introducing_smarter_api_documentation https://blog.apigee.com/detail/apigee_smartdocs_introducing_... (top level readers: sorry about the double-post)
        anonfunction 12y ago
        Why the apigee links? We want to see what this guy built over a week.
        orliesaurus 12y ago
        sad to see the spam indeed
        12y ago
butner 12y ago
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
jefftratner 12y ago
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.
chatmasta 12y ago
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/

68 points by orliesaurus 12y ago

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 12y ago
Thanks for leaving your feedback and comments. See you here, drinks on us.
- fosk 12y ago
  Mashape is at 500 Montgomery Street in San Francisco, if you HN guys want to join us for drinks tonight ;-)

bvanvugt 12y ago

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 12y ago
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 12y ago
  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 12y ago
    whats it called? is it public?
    - illicium 12y ago
      Check out Apigee SmartDocs: https://blog.apigee.com/detail/apigee_smartdocs_introducing_smarter_api_documentation https://blog.apigee.com/detail/apigee_smartdocs_introducing_... (top level readers: sorry about the double-post)
      - anonfunction 12y ago
        Why the apigee links? We want to see what this guy built over a week.
        orliesaurus 12y ago
        sad to see the spam indeed
        12y ago

butner 12y ago

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

jefftratner 12y ago

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.

chatmasta 12y ago

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/