Hacker News new | comments | show | ask | jobs | submit login
API Documentation and the Communication Illusion (jamescooke.info)
32 points by wallflower on May 11, 2016 | hide | past | web | favorite | 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.


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.


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.


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.




Guidelines | FAQ | Support | API | Security | Lists | Bookmarklet | Legal | Apply to YC | Contact

Search: