API Documentation and the Communication Illusion

jamescooke.info

32 points·wallflower··8 comments

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.

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.

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.

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!

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

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.

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

Looks interesting! Thanks.

Reply on news.ycombinator.com