51–59 of 59 posts
Any recommendations on good doc frameworks/products? We're about to begin redoing our documentation at print.io. Currently we're using swagger ( https://api.print.io/docs/ ) and "self-documentation" ( http://print.io/api ) but i still find that we have a lot of questions.
It all depends on what kind of API you're building. If you're implementing a RESTful API, no documentation is needed, as it is "surfable" due to the use of hyperlinks. If you're implemeting an RPC API (which is what most of us are doing), good and up-to-date documentation is key, as we need to document each and every meaningful end-point.
I'm working on integrating Braintree payments into a client of mine. Braintree is a perfect example of this and is a wolf in sheep's clothing, meaning, their docs look great at first glance until you need to get all the way through them. For example, you start reading about how to do A. Half way through, you find out you need to do B. So you look at the link to B which then refers to C but C is A and you realize you'…
We're actively trying to fix the flow issues by consolidating information so you don't have to go tab-hopping to find what you need. If all goes well, hopefully you'll see some improvements showing up very soon™.
If there's a specific problem you'd like to share, I'd welcome the feedback. Either way, we'll keep forging ahead on another rev that's a little easier to follow.
Any recommendations on good doc frameworks/products? We're about to begin redoing our documentation at print.io. Currently we're using swagger ( https://api.print.io/docs/ ) and "self-documentation" ( http://print.io/api ) but i still find that we have a lot of questions.
Definitely check out http://readme.io . Their docs look beautiful and set-up is a breeze.
Also, plugging: Swagger support in just a few weeks. And we can currently auto generate endpoint reference docs from your source code using a commenting standard similar to javadoc.
We get all sorts of excited by good API documentation. Weird, right? Apparently not, based on this thread. :D
Earlier quoted context omitted.
Had to do a little searching, but here it is: https://app.ticketmatic.com/api/doc
(Author here) Nope, that's the old one for V2 (which isn't very good). We're currently releasing the third generation of the Ticketmatic platform, where one of the big efforts is in improving the developer story. That's not public yet, for which I apologise. There will be a beautiful developer program soon. I didn't think that the article should wait on that. It's the idea that matters and didn't want any discussion…
Earlier quoted context omitted.
I know what REST is. Congratulations, I now have a URL and a JSON file the URL spits out. I still have no idea what the significance of all the values are. I have no idea what their possible ranges are. I don't know how everything works together. Edit: Also, that's just GET. If you expect me to poke around with POST to learn how your API works, I will run far, far away.
So you don't know what REST is (and didn't read the link I posted earlier).
Even in your link it is plainly obvious that there is no provision for documenting what an endpoint does, or how to find what endpoint maps to something, or even how to query this magical introspective API to figure out what further requests you need to make.
I'm working on integrating Braintree payments into a client of mine. Braintree is a perfect example of this and is a wolf in sheep's clothing, meaning, their docs look great at first glance until you need to get all the way through them. For example, you start reading about how to do A. Half way through, you find out you need to do B. So you look at the link to B which then refers to C but C is A and you realize you'…
I would have been better off if they didn't supply that doc at all. If I just fumbled my way through an undocumented pile of service endpoints, I'd have realized its limits much sooner. The doc gave me the false-confidence to build my application based on behaviours in their API which aren't actually implemented.