
An API is only as good as its documentation - rubenv
https://rocketeer.be/blog/2015/03/api-quality/
======
cbd1984
Good documentation includes examples.

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.

------
jedisct1
I'd rather say an API is only as good as the clients/libraries for it.

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.

~~~
ddlatham
Providing a client or library is great, but serves to shift the actual API to
be that which the client or library provides. Ultimately there is some
interface between what you provide and your customer. That's the point you
need to make as well understood as possible. A clean, intuitive interface and
good documentation are both valuable in making it understood.

------
pavlov
I have a corollary of sorts:

 _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.

~~~
rprospero
I find your comment about Rails facinating, as it teaches me a bit about how
I'm a Blub programmer.

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.

~~~
TeMPOraL
I don't think this is about being a Blub programmer. Rails is a complex web
framework that is designed to help solve many common problems in web
development. Therefore, it has tons of code organized in an arcane way you
won't understand until you know _what problems it 's trying to solve_.

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.

~~~
beat
The problem, then, isn't that we shouldn't _use_ complex frameworks like
Rails, but rather we shouldn't _teach_ with frameworks like Rails. In order to
teach Ruby-based web development to the n00bs, use Sinatra. This forces them
to address the Ruby language right away, learn http verbs, learn unit testing
(well, if I'm teaching them anyway), learn templates, and learn to organize
code from a single file up to a simple structure like a gem.

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.

~~~
TeMPOraL
Exactly this.

> _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.

------
jasonlotito
The irony of this statement

"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.

~~~
baconomatic
Had to do a little searching, but here it is:

[https://app.ticketmatic.com/api/doc](https://app.ticketmatic.com/api/doc)

~~~
rubenv
(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 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.

~~~
Sanddancer
I think that your redevelopment of API documentation would be an interesting
series of blog articles in and of themselves. Giving examples of bad
documentation decisions, giving examples of how they were corrected in the new
documentation, etc. There are lots of examples of refactoring code, but
entirely too few that deal with refactoring the manual.

------
micahasmith
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/](https://api.print.io/docs/)) and
"self-documentation" ([http://print.io/api](http://print.io/api)) but i still
find that we have a lot of questions.

~~~
timjones
Definitely check out [http://readme.io](http://readme.io). Their docs look
beautiful and set-up is a breeze.

~~~
gdillon
Thanks for the tip, Tim! Happy to answer any questions folks have about my
product.

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

------
amelius
I wish we could have "documentation day" on github, where all project
maintainers would spend one whole working day on documenting as much as they
possibly can.

~~~
prottmann
Not enough. Its more fun to create software, but documentation is the part
that no one likes. It is absolutely necessary, in particular when other work
with your code.

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.

------
shivang
A very valid point raised by the author. Having worked with multiple api's i
can say that developers start preferring that product which has better api
docs than the other product which has a crappy doc inspite of having many
features.

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.

------
rkn7
Completely agree with this. I've been trying to set something up with the
Trello API all weekend and it's been a nightmare.

~~~
jfaucett
+1 for feeling your pain, had the same nightmare myself about 6 months ago.

------
BetaMechazawa
I'm currently working on a libre push notification service (Heavy WIP) and
since this post is about API's and Documentation I was wondering if mine is
any good.

It requires javascript for the "full experience".
[https://api.pushjet.io](https://api.pushjet.io)

Should I redo it? Are there things I should change?

~~~
onion2k
It's really not even close to being verbose enough. A good API doesn't just
give you the name of the endpoint and what it's expecting - it should
_explain_ what the endpoint is for. Your documentation assumes the user
already knows what they're going to implement in terms of your API (eg they
know that they'll need to create a 'service' that other clients will 'listen'
on, and so on.

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"
        }
      }
    

I assume that means it's already connected, but should that be the case in an
example of creating a connection?

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](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](https://www.firebase.com/tutorial/#gettingstarted)

~~~
BetaMechazawa
The API documentation is talking to the live version of the application. The
pre-filled variables can be used for quick testing but this also means that
when you make the default user (UUID) listen to the default service it will
tell you that it's already doing that. Changing the UUID should be sufficient
to give it a non-error response for that API call.

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.

------
NKCSS
I think it's when you try to separate code and documentation that things tend
to get out of sync quite easily.

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.

------
gtramont
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.

~~~
steveklabnik
The problem with this "no documentation" stance, as you've seen below, is that
it doesn't get the correct message out to those who haven't studied
hypermedia.

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.

~~~
gtramont
My premise was, when I wrote the first post, that REST is understood. Not a
surprise that it is not…

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).

------
CyberDildonics
I would say that an API's usefulness is the complexity it hides divided by the
complexity of its interface.

------
crystaln
Not to discount the importance of good documentation, but this is not true.
Many of the best uses of APIs historically have actually come from reverse
engineering undocumented APIs.

------
orliesaurus
rubenv what's your view on mashape.com documentation portal?

------
wantab
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'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!

~~~
gbramwell
Hi, I'm one of the devs working on the Braintree docs. You're absolutely
right, the information flow in our docs isn't in a great state right now.

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.

