Show HN: Stoplight – Visual API Tooling | Hacker News Reader

Show HN: Stoplight – Visual API Tooling

stoplight.io

57 pointstonytony24 comments

Hi HN! Stoplight is launching today. It's the worlds first visual API designer. That means anyone can use it, even Jane in customer support.

This means businesses can develop their best API by making it accessible to everyone. Ultimately this saves large companies a lot of time and money, and improves the user experience.

We're also launching API Docs today, it's hosted API documentation for every OAI (Swagger) and RAML spec out there.

I'd love to get your feedback on Stoplight, and answer any questions you might have!

First impression: after looking over the homepage, the 9 "Get Started - It's FREE" buttons made me hunt in the footer for "Pricing" or more information before signing up, because usually that tactic says "free trial, but then you want my money" to me.

Second impression is that it seems like a Swagger Editor tool combined with a REST Explorer (like Postman or Advanced REST Client). Testing now and will update with some more thoughts :)

It really is free, for individual use, forever :). Pricing starts at the team level - at $8/month/member. We're also introducing cheaper, annual pricing soon.

The hosted documentation integration is completely free - we have a paid option coming soon, that adds custom domains, theming, analytics, etc.

Eager to hear what you think - let us know!

Yeah, the copy kind of indicated to me that there was some pricing scheme coming, but there is no indication (or info) about that on your site. Just something to remember if you're going to take a little time to add the Pricing details :)

Nice tool, the Prism integration looks really nice.

Some feedback:

- The left hand menu for API, versions, documentation (or something) totally confuses me. Even after thinking about it for multiple minutes I don't really get it. I think there are multiple things being represented by the same interface type, but I'm not sure.

- Sometimes action buttons on top, action buttons on the bottom.

- Prism... where is it? Why does the main interface change when I switch from "hosted" to "local"? What does "local" actually mean?

You have a really nice tool, but for now it was too complicated for me :/ Some UI and usability love would probably help quite a lot.

Really great feedback, thanks! We've heard that the main navigation is confusing, and are working on improving it as I type this. Could you send me an email marc @ stoplight.io? I would love to bounce some of our ideas off of you, and hear what you think.

Wow this is really great. Interested in how the prism proxy thing can work for reversing existing (un-specced) APIs. Can you shed some light on that?

Hey! Marc MacLeod here - founder. Basically, you put Prism between your API consumer (mobile app, website, integration tests, library, curl request, whatever) and the API itself.

Prism processes the traffic that passes through it, and generates your spec code from that. It can identify dynamic parameters in the url, build json schemas, etc.

Here's a little post + video we put together: https://medium.com/oh-what-a-wonderful-web/how-to-generate-2...

And another, demonstrating a slightly different process of generating spec code from the Peach mobile app API traffic:

http://peach.api-docs.io/1.0/welcome

Just something I've noticed - Looks like generating schema from an example doesn't support multiple value types. Eg. when the first object's value is string and the next one's is null, it saves it as a string field in the schema and throws an error for the example.

Astute catch! We're actually tracking this issue internally already. We'll be beefing up that generator to aggregate multiple values for the same property, when it's an array of objects. Look for that in an update in the next 2 weeks.

Looks really cool, nice work!

Any thoughts on import from Apiary/Blueprint?

Great question! We are considering adding first class support for Blueprint. In the meantime, we recommend converting first to OAI/Swagger with the awesome tool over at https://apitransformer.com

Looks awesome! I'm excited to try the API documentation tool.

FYI if you haven't clicked on the animation on homepage, do it...it's addicting

Is there a way to make my documentation private? Secret URL or just for people in the team?

You can invite team members to your workspace in the API Designer, and only they will have access (read or read/write) to the APIs in that workspace.

From the API Designer (which is private), you can optionally publish any of your API versions out to api-docs.io, for public consumption. You don't even need to publish your entire API definition out - you can mark which endpoints/models are private versus public. Only the parts of your internal docs marked as public will be published out :).

Makes sense. Great tool, thanks!

Looks like a real solution instead of just a text editor like others out there.

I checked this out last night, going to get a POC running for sure.

Awesome, let us know if you run into any issues, or have suggestions - we're here to help. You can reach me directly at marc@stoplight.io.

How complete should the published documentation be? I see the headers I defined, but not the query params.

Also, I define the OAuth2 security in the version, but it shows up nowhere else except for the exports. It would be nice if you define which resources are secured by what. For instance all of my resources require apikey as well as an OAuth2 token.

Interesting, query params should be published - could you send me the link to the docs you published?

In the "settings" tab for each endpoint, you can mark which security schemes apply to the endpoint. It's kind of hidden, we're moving it to the general definition tab. Also, that info will be exposed in api-docs (which security schemes an endpoint requires/supports) in an update later this week!

Oh! There it is. Email incoming!

Are you related to SendGrid?

Hey there, nope! They are one of our beta customers though.

They blogged about their experience so far with our tools here: https://sendgrid.com/blog/using-a-prototype-as-an-api-produc...

Reply on news.ycombinator.com