News for hackers. Stuff that matters.
Re:API Documentation and the Communication Illusion by zer00eyz on Wednesday May 11, 2016 @02:42PM (#11678020)
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.

Re:API Documentation and the Communication Illusion by clay_to_n on Wednesday May 11, 2016 @06:36PM (#11679922)
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.

Re:API Documentation and the Communication Illusion by Ysx on Wednesday May 11, 2016 @02:48PM (#11678074)
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.
Re:API Documentation and the Communication Illusion by tmwilder on Wednesday May 11, 2016 @08:18PM (#11680455)
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!

Re:API Documentation and the Communication Illusion by Animats on Wednesday May 11, 2016 @06:02PM (#11679703)
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

Re:API Documentation and the Communication Illusion by ktRolster on Wednesday May 11, 2016 @08:06PM (#11680402)
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.

Re:API Documentation and the Communication Illusion by jzd131 on Wednesday May 11, 2016 @06:13PM (#11679783)
Check out http://apifortress.com/ I believe they do the exact testing your looking for.
Re:API Documentation and the Communication Illusion by jamescooke on Thursday May 12, 2016 @06:21AM (#11682452)
Looks interesting! Thanks.