An API is only as good as its documentation
rocketeer.be
rocketeer.be
Good documentation does not rely on examples.
An example can provide a base to start from, a beginning point from which further hacking can ensue.
However, an example, like a picture, can't say "ain't": Examples can only show you what you can do, never what you cannot do, or what you should not do.
Further, examples are inductive, and it takes a massive amount of induction to get all of the rules of a system. However, once someone's done something, they've internalized it a lot better than if they've only read about it.
Examples should, therefore, allow people to see the intended use of an API. How do the developers want people to use their API to solve problems?
Documentation is permissive: "You can use this tool to do this."
Examples are normative: "You should use this tool this way."
Both are needed. I focus on examples because good examples are not as common as they should be.
Having an API is nice, documenting it is nice, but this is not what developers are going to use.
If you only publish API documentation, you will end up with tons of half-baked, soon-to-be-unsupported, incompatible client libraries.
And until then, people will have to roll their own clients based on the documentation, which is not fun. Nobody wants to reinvent a REST client, deal with errors, timeouts, data conversion and how to match the API with actual use cases.
Especially when evaluating a new service, the last thing you want is have to read an API documentation before being able to do anything with the service.
Take MySQL. The protocol is all binary, and mostly undocumented. Yet, it's used everywhere because the MySQL maintainers are shipping a C library on top on which people built bindings.
Same for MongoDB. Even though there are alternative/additional client libraries, they are maintaining client libraries for many languages. Getting started with MongoDB is easy; one doesn't have to read an API documentation at all.
What if changes have to be made to the API? If the same team maintains the reference client libraries, it can be totally transparent to users. If you expect people to write their own client, it will be painful.
Please provide good reference client libraries so that people can immediately use the service, even before thinking about API documentation. And writing client libraries is also a good way to realize what's broken/inconvenient in the API.
A framework is only as good as its UI.
This is a widely neglected point. Only game engines tend to understand this fully (e.g. Unreal Engine's editor). But Smalltalk and NextStep/Cocoa had a grasp of this too.
Even without a GUI, the interface matters. Rails' "generate" and "console" commands are a major part of its appeal.
In the end it all generalizes to "Your product is only as good as its experience".
I've tried to learn Rails multiple times and the "generate" and "console" commands have always been a massive stumbling block for me. With ever other language and toolkit I've ever worked with, the tutorial starts with opening up a text editor, writing some code, and producing a lousy, "Hello World" website. With Rails, I went through three pages of the tutorial before I even saw a single line of Ruby. I grew to hate the "generate" command, as it produced ever expanding reams of unexplained code each time the tutorial had me call it.
I had always assumed that the elimination of the need for commands like "generate" would be the top priority of the Ruby community and that their existence was a recognized design wart, like Python's GIL or Haskell's unsafe prelude. That "generate" would actually appeal to someone is something that I'd never even considered. That makes me a Blub programmer and tells me that there's another whole philosophy of programming that I need to learn about.
That's why I always found teaching RoR (or equivalent frameworks in your language of choice) to beginners completely backwards. What the newcomer learns is how to tweak this huge blob of arcane magic here and there, and gains almost zero actual understanding of how things work. My preferred way of teaching webdev is showing how text goes from server to browser, how the browser parses it to render a page, and how a programming language is used to generate such text. And then I build up from this base. Sure, this approach won't make one a Rockstar Full-Stack Code Ninja in half a week, but at least the student has some solid foundation of understanding to work from and can comprehend why Rails looks the way it looks.
It also seems to me that the current trend in web development is people using huge complex tools, of which they need 1% and understand 0.1%, and thus generating layers upon layers of bloat. But my opinion here is probably biased as I hate webdev more and more with every single day I spend working in it.
Once they grok a simple Sinatra app, they can move on to Rails, understanding that it's doing a lot of magic, but at least having a grasp of how the magic works.
> Once they grok a simple Sinatra app, they can move on to Rails, understanding that it's doing a lot of magic, but at least having a grasp of how the magic works.
How the magic works, and why it's needed in the first place.
"At Ticketmatic, we promise that anything you can do through the user interface is also available via the API."
in the context of the article is amusing. Going to the website, I find no mention of an API anywhere. I can only guess that it's API documentation hidden behind a login. This is the worst kind of API documentation. I've dealt with APIs like this far too often to find it friendly. In every case, it's been frustration.
Regardless, while the platitude is agreeable, this is literally an article that says nothing more than what fit into a tweet.
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 to turn into a nitpicking over what we did right (and wrong).
This article mostly came out of a frustration with bad API documentation and I was hoping to inspire people to do (slightly) better.
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.
Disclaimer: I work at Apiary
Real documentation is written by a person who understands how to use the API.
Unfortunately, such documentation then suffers bit-rot if it's not updated whenever the API is updated.
What I would like to see is some way to describe an API which can be merged with the hand-written narrative and instructions, and can be refreshed whenever the implementation changes.
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
And we have many stages of documentation: the project documentation (what is it, what does it, how, ...), the code doc, the rest-api doc. And it get really complex on further development. I think that is one reason for the small JS project explosion on npm / github of the last years.
I was working with PayPal few years back and there are bunch of apis that they provide, but the explanation and usage is so bad that you end up spending a lot of unnecessary time figuring out what to do. And then i came to Stripe integration. They have beautiful apis which can be integrated smoothly and very easily. I tell developers to follow Stripe's api for writing documentation and examples.
It requires javascript for the "full experience". https://api.pushjet.io
Should I redo it? Are there things I should change?
I like your "try-this-request", however IMHO it is missing a "request is in progress..." kind of indicator - clear the output space and add a spinner? I had to look in the developer tools to ensure that it works.
Finally, not all things work: 'Websockets/Run Example' doesn't do anything. In the background there is a 500: 'WebSocket connection to 'wss://api.pushjet.io/socket' failed: Error during WebSocket handshake: Unexpected response code: 500'. In your defense, you do mention that "Websockets are really iffy at the the moment and are currently in the process of being redone". But still, better capture that error and show it somehow.
All in all, ahead of the curve ;) Some UI lovin' would put you at the head of it.
Also, what's especially unhelpful in your documentation is the fact your example code returns errors. In the /listen POST documentation clicking the Send button displays
{
"error": {
"id": 4,
"message": "Already listening to that service"
}
}
EDIT: My post would be more useful with an example of how verbose I think you should be. Firebase gets it right - https://www.firebase.com/docs/web/quickstart.html - and their brilliant interactive tutorial that really drives home how easy it is to use - https://www.firebase.com/tutorial/#gettingstarted
I'll add some documentation about what endpoints do and what kind of "flow" an application needs to interact with the API when I get home from work. I'll also finish my quick start guide while I'm at it then.
For example; we have a settings system; all keys are defined as constants in code and they have attributes that clearly describe every aspect which is the used to generate the documentation. If you add a new settings, you instantly write the documentation for it as well; so far, it has worked great and I think this could/should work for other parts of the code as well.
I would not want to code against your API.
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.
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 like to make an analogy to RSS: If I told you, "Here's a link to my RSS feed." You wouldn't be mad at me for that, since all you need is RFC 822. By the same token, hypermedia/"real REST" APIs don't have _no_ documentation: they have no _specific_ documentation about _this_ particular API.
Without a foundation in this approach towards building and consuming APIs, "no documentation" sounds like a disaster. And it is, in that context.
I totally agree with you… And what I've been trying to do to whoever I talk to, in my team and outside, is to educate them in this area (sending resources like I did on an earlier post), and try to make them not call any json-based API REST (which in fact has nothing to do with json specifically).
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're in a loop.
So then you try their search function, or Google, but then you find yourself linked to either outdated docs that look like the same thing or articles about the subject which give no detail.
It's spaghetti documentation mixed with out of date spaghetti mixed with meatballs. At this moment, I have 13 tabs open to various parts of the docs trying to piece things together to understand how to make it work and, sometimes, I find the out of date docs more understandable!
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.
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.