5 ms·

Apiary: Beautiful API docs, raises seed round, adds premium features

118 points by zzen 13y ago

bdesimone 13y ago
Congrats on the funding. However, I'm not sure what Apiary does, or why I'd use it. Could someone help me? Is it an API mocking tool? A documentation tool? Both? Can I use it next to my existing source tree?
- Almad 13y ago
  Hi, thanks! Yes, it is both and yes, you can add it to your source tree through our github integration. Our idea is to have a human-readable, human-writeable DSL to describe your API. From there, we generate both documentation, mocks, debugging proxy and tests. You can use it to describe your existing APIs, but in my mind, our biggest value lies in conversation around API design that happens before you start implementing. Hope this helps!
  - stingraycharles 13y ago
    Hi, I'm not sure if I'm alone in this, but I personally hate to document my code outside my code. Is there any way to make apiary scan my existing codebase for, say. API documentation and generate docs based on that?
    - Almad 13y ago
      Hi, there are some 3rd party works in progress and we will promote them. We are leaving this to community though, as respective languages/frameworks are best supported by people that use them. And as said -- Apiary is more about design than documentation and writing blueprint should take place before writing code. A lot of things is lost when it's the other way around.
killahpriest 13y ago
Is is just me, or are their docs kind of yuck/hard to read? http://docs.timdorr.apiary.io/#vehiclecommands http://docs.timdorr.apiary.io/#vehiclecommands My biggest problem: way too much visual emphasis on 'GET' part and not enough on the actual URL. That has way more priority, to me.
- jonahx 13y ago
  I think they look great. I could imagine having a few nitpicks, but never describing them as "yuck"
- deleted 13y ago
  [deleted]
- tieTYT 13y ago
  I like the swagger layout. http://swagger.wordnik.com/#!/pet http://swagger.wordnik.com/#!/pet Their developer documentation is kind of tricky to figure out though.
  - StavrosK 13y ago
    I liked swagger a lot, but could never get it working with my API because it's too opinionated. From the little I tried to do, there was no way at all to tell it to document the API the way I had designed it, rather than the way it thought APIs should be designed.
  - joshguthrie 13y ago
    Nice layout. Reminds me of IO/Docs which I use actively for my own application. I like the ability to "try it yourself" though a mix of it with "here is the default response if it works, here is the response if it fails" is better for POST/PUT/DELETE routes.
- ktsmith 13y ago
  I actually agree and find them very unappealing. They seem too dense and the text either too light, too small, or both.
deleted 13y ago
[deleted]
Ono-Sendai 13y ago
"Brigtht Future for Us All"
- zzen 13y ago
  Thanks for pointing out the typo. Fixed.
shunter 13y ago
This is awesome.. And Immediately runs into the problem of being purely SaaS. I can't use this for APIs that I develop internally within my 'Big Company'. If I could host this somewhere behind my firewall, then something like this becomes a no brainer. But making me try to convince my security team to send all of my API calls and design to an external service puts a huge barrier to entry for me politically. I love the idea to the point that I started searching for something similar that I could host inside. Even Github lets me host a copy of their software somewhere nice and corporate safe. I wish more service providers would offer more than just 'pure SaaS' to allow for easier adoption by corporate customers.
- Almad 13y ago
  I do believe we'll be providing on-premise instances as Github does in the future. However, as github hasn't provided this from year one, so are we. Choosing priorities is hard in startup and on-premise takes a lot of resources. ...which is what seed is for ;) Meanwhile, you can still use our format separately from Apiary SaaS. Please take a look: http://apiblueprint.org/ http://apiblueprint.org/
thangalin 13y ago
A number of related solutions for web services integration: http://programmers.stackexchange.com/a/181593/16090 http://programmers.stackexchange.com/a/181593/16090
- zzen 13y ago
  Not sure how we've ended up in that category. Apiary doesn't generate or manage license keys. And frankly, it doesn't do API management at all. We're helping people design & build APIs.
  - thangalin 13y ago
    Thanks for pointing that out! When I was researching the topic of API management earlier this year, Apiary.io was in beta. If you'd like, I can take it out of the list.
hopopopo 13y ago
I love the design! I think it is great :)
nopassrecover 13y ago
The mock server generated out of a minimal markdown-like syntax seems pretty cool. As far as the docs themselves I think I prefer the design of something like Swagger (https://developers.helloreverb.com/swagger/ https://developers.helloreverb.com/swagger/).
connerbryan 13y ago
Awesome. I really like the design and simplicity. From the example on http://apiary.io/how-it-works http://apiary.io/how-it-works how are language bindings generated? How do you know the schema of a message? I've actually been working on something similar, but more focused on library generation and like a "npm for APIs", e.g. reusable schemas. Instead of markdown I'm using something more akin to Google's Discovery Document (https://developers.google.com/discovery/v1/reference/apis#resource https://developers.google.com/discovery/v1/reference/apis#re...).
dreamdu5t 13y ago
Good luck... Love the design. I can't help but wonder... a person experienced enough to design a REST API wouldn't need or want to rely on said service just to mock it up. I don't see a market for Apiary. At least in the node.js community, there are lots of tools and projects for mocking REST APIs. Why should I spend the time to sign-up and pay for Apiary, when I could already mock an API in that time instead? > TCP dumps, Wireshark, installing local HTTP proxies… Not fun. Developers should be able to debug the freakin' API they are supposed to be building! If someone needs Wireshark or HTTP proxies to debug their code, they are doing it very wrong.
- Almad 13y ago
  > Your developers suck if they can't debug the freakin' API they are supposed to be building. You're doing it very very wrong if you need wireshark or HTTP proxies to debug your code. And what if I am using a library to connect to a 3rd party service (i.e. github) and I'd like to debug my API calls?
  - dreamdu5t 13y ago
    You shouldn't be coding things to be so tightly coupled. You should be able to build and test your API without communicating with a 3rd party. Sure, there are cases where you have to use a proxy to see a request. I'm surprised there's a market for people who pay for that.
    - johns 13y ago
      There are so many scenarios for debugging APIs that don't fall into the "I control both ends, so I should be able to see everything." camp. SDKs, poorly implemented or documented APIs controlled by a 3rd party (frequently even across a company where the people producing are far removed from the consumers), differing environments (works locally, not in staging, etc), UI-less machine-to-machine interactions (debugging webhooks is especially annoying) and many more. If you check my bio, you'll see my bias toward these problems. But there are a lot more of them and a lot more variants than you give credit to.
jaytaylor 13y ago
Does anyone know how this compares to wordnik's Swagger [1] ? I think Swagger is incredible, would love to see more API tools which promote good habits and make it easy to be beautiful. [1] https://developers.helloreverb.com/swagger/ https://developers.helloreverb.com/swagger/
deleted 13y ago
[deleted]
sinzone 13y ago
I'm bit biased. I'm running a marketplace for APIs since 2010 but defining itself like the largest API Hub is a bit false. It's doesn't matter how many APIs you have, since the majority of those are "fake, draft, etc" not real working APIs, they are mocks. What makes you substantial is: 1) # of API transactions passing via you "apps in production running on you", 2) # of total active developers in your community "hub = consumers + providers not just one side" 3) money "enterprise customers, revenue, subscriptions, etc" Real activity, not mocks.
contingencies 13y ago
In related news nobody upvoted, rich-client focused web APIs may be becoming an endangered species: https://news.ycombinator.com/item?id=6392022 https://news.ycombinator.com/item?id=6392022
philjackson 13y ago
Amazing news, well done Apiary.

118 points by zzen 13y ago

Congrats on the funding. However, I'm not sure what Apiary does, or why I'd use it. Could someone help me? Is it an API mocking tool? A documentation tool? Both? Can I use it next to my existing source tree?

Almad 13y ago
Hi, thanks! Yes, it is both and yes, you can add it to your source tree through our github integration. Our idea is to have a human-readable, human-writeable DSL to describe your API. From there, we generate both documentation, mocks, debugging proxy and tests. You can use it to describe your existing APIs, but in my mind, our biggest value lies in conversation around API design that happens before you start implementing. Hope this helps!
- stingraycharles 13y ago
  Hi, I'm not sure if I'm alone in this, but I personally hate to document my code outside my code. Is there any way to make apiary scan my existing codebase for, say. API documentation and generate docs based on that?
  - Almad 13y ago
    Hi, there are some 3rd party works in progress and we will promote them. We are leaving this to community though, as respective languages/frameworks are best supported by people that use them. And as said -- Apiary is more about design than documentation and writing blueprint should take place before writing code. A lot of things is lost when it's the other way around.

killahpriest 13y ago

Is is just me, or are their docs kind of yuck/hard to read? http://docs.timdorr.apiary.io/#vehiclecommands http://docs.timdorr.apiary.io/#vehiclecommands My biggest problem: way too much visual emphasis on 'GET' part and not enough on the actual URL. That has way more priority, to me.

jonahx 13y ago
I think they look great. I could imagine having a few nitpicks, but never describing them as "yuck"
deleted 13y ago
[deleted]
tieTYT 13y ago
I like the swagger layout. http://swagger.wordnik.com/#!/pet http://swagger.wordnik.com/#!/pet Their developer documentation is kind of tricky to figure out though.
- StavrosK 13y ago
  I liked swagger a lot, but could never get it working with my API because it's too opinionated. From the little I tried to do, there was no way at all to tell it to document the API the way I had designed it, rather than the way it thought APIs should be designed.
- joshguthrie 13y ago
  Nice layout. Reminds me of IO/Docs which I use actively for my own application. I like the ability to "try it yourself" though a mix of it with "here is the default response if it works, here is the response if it fails" is better for POST/PUT/DELETE routes.
ktsmith 13y ago
I actually agree and find them very unappealing. They seem too dense and the text either too light, too small, or both.

deleted 13y ago

[deleted]

Ono-Sendai 13y ago

"Brigtht Future for Us All"

zzen 13y ago
Thanks for pointing out the typo. Fixed.

shunter 13y ago

This is awesome.. And Immediately runs into the problem of being purely SaaS. I can't use this for APIs that I develop internally within my 'Big Company'. If I could host this somewhere behind my firewall, then something like this becomes a no brainer. But making me try to convince my security team to send all of my API calls and design to an external service puts a huge barrier to entry for me politically. I love the idea to the point that I started searching for something similar that I could host inside. Even Github lets me host a copy of their software somewhere nice and corporate safe. I wish more service providers would offer more than just 'pure SaaS' to allow for easier adoption by corporate customers.

Almad 13y ago
I do believe we'll be providing on-premise instances as Github does in the future. However, as github hasn't provided this from year one, so are we. Choosing priorities is hard in startup and on-premise takes a lot of resources. ...which is what seed is for ;) Meanwhile, you can still use our format separately from Apiary SaaS. Please take a look: http://apiblueprint.org/ http://apiblueprint.org/

thangalin 13y ago

A number of related solutions for web services integration: http://programmers.stackexchange.com/a/181593/16090 http://programmers.stackexchange.com/a/181593/16090

zzen 13y ago
Not sure how we've ended up in that category. Apiary doesn't generate or manage license keys. And frankly, it doesn't do API management at all. We're helping people design & build APIs.
- thangalin 13y ago
  Thanks for pointing that out! When I was researching the topic of API management earlier this year, Apiary.io was in beta. If you'd like, I can take it out of the list.

hopopopo 13y ago

I love the design! I think it is great :)

nopassrecover 13y ago

The mock server generated out of a minimal markdown-like syntax seems pretty cool. As far as the docs themselves I think I prefer the design of something like Swagger (https://developers.helloreverb.com/swagger/ https://developers.helloreverb.com/swagger/).

connerbryan 13y ago

Awesome. I really like the design and simplicity. From the example on http://apiary.io/how-it-works http://apiary.io/how-it-works how are language bindings generated? How do you know the schema of a message? I've actually been working on something similar, but more focused on library generation and like a "npm for APIs", e.g. reusable schemas. Instead of markdown I'm using something more akin to Google's Discovery Document (https://developers.google.com/discovery/v1/reference/apis#resource https://developers.google.com/discovery/v1/reference/apis#re...).

dreamdu5t 13y ago

Good luck... Love the design. I can't help but wonder... a person experienced enough to design a REST API wouldn't need or want to rely on said service just to mock it up. I don't see a market for Apiary. At least in the node.js community, there are lots of tools and projects for mocking REST APIs. Why should I spend the time to sign-up and pay for Apiary, when I could already mock an API in that time instead? > TCP dumps, Wireshark, installing local HTTP proxies… Not fun. Developers should be able to debug the freakin' API they are supposed to be building! If someone needs Wireshark or HTTP proxies to debug their code, they are doing it very wrong.

Almad 13y ago
> Your developers suck if they can't debug the freakin' API they are supposed to be building. You're doing it very very wrong if you need wireshark or HTTP proxies to debug your code. And what if I am using a library to connect to a 3rd party service (i.e. github) and I'd like to debug my API calls?
- dreamdu5t 13y ago
  You shouldn't be coding things to be so tightly coupled. You should be able to build and test your API without communicating with a 3rd party. Sure, there are cases where you have to use a proxy to see a request. I'm surprised there's a market for people who pay for that.
  - johns 13y ago
    There are so many scenarios for debugging APIs that don't fall into the "I control both ends, so I should be able to see everything." camp. SDKs, poorly implemented or documented APIs controlled by a 3rd party (frequently even across a company where the people producing are far removed from the consumers), differing environments (works locally, not in staging, etc), UI-less machine-to-machine interactions (debugging webhooks is especially annoying) and many more. If you check my bio, you'll see my bias toward these problems. But there are a lot more of them and a lot more variants than you give credit to.

jaytaylor 13y ago

Does anyone know how this compares to wordnik's Swagger [1] ? I think Swagger is incredible, would love to see more API tools which promote good habits and make it easy to be beautiful. [1] https://developers.helloreverb.com/swagger/ https://developers.helloreverb.com/swagger/

deleted 13y ago

[deleted]

sinzone 13y ago

I'm bit biased. I'm running a marketplace for APIs since 2010 but defining itself like the largest API Hub is a bit false. It's doesn't matter how many APIs you have, since the majority of those are "fake, draft, etc" not real working APIs, they are mocks. What makes you substantial is: 1) # of API transactions passing via you "apps in production running on you", 2) # of total active developers in your community "hub = consumers + providers not just one side" 3) money "enterprise customers, revenue, subscriptions, etc" Real activity, not mocks.

contingencies 13y ago

In related news nobody upvoted, rich-client focused web APIs may be becoming an endangered species: https://news.ycombinator.com/item?id=6392022 https://news.ycombinator.com/item?id=6392022

philjackson 13y ago

Amazing news, well done Apiary.