API Documentation and the Communication Illusion

[wallflower]

http://jamescooke.info/api-documentation-and-the-communication-illusion.html

[zer00eyz]

Hey guys lets write documentation first, it will be great and clear everything up.

Isn't this how waterfall development was/is supposed to work.

[clay_to_n → zer00eyz]

Based on organization structure, and your timing, there's a point where it's necessary.

If you have separate teams designing the client and server, you'll eventually get to a point where you need to agree on the messages passed.

[Ysx → zer00eyz]

Unless you have an infinite number of monkeys, there's likely some design to your API. This doesn't need to be documentation, but it can be.

[tmwilder]

You might find this project interesting: http://swagger.io

We use it to document services by reflecting docs off of the implemented service. Upside, no drift!

[Animats]

Of course you write the documentation first. Both provider and user need it so they both talk to the same interface.

Here's an API document I wrote.[1] Comments?

[1] http://sitetruth.com/doc/sitetruthapi.html

[ktRolster → Animats]

Here's an API document I wrote.[1] Comments?

You asked, so:

The organization can be better. Usually when I am looking at an API, the first question I have is, "What is this API, what can I do with it?" There's one sentence about that in the header, but it's not very clear. Then you jump right into low-level protocol details. Your pictures are good, and help to understand, but they come way late.

The broad organization should be something like: 1 "Here's what you can do with this API" 2 "Here's how to use it" 3 "Here are the fine details" and maybe (4 "Legal garbage")

Nice quote at the bottom.

[jzd131]

Check out http://apifortress.com/ I believe they do the exact testing your looking for.

[jamescooke → jzd131]

Looks interesting! Thanks.