5 ms·
API Documentation and the Communication Illusion
- zer00eyz 10y agoHey guys lets write documentation first, it will be great and clear everything up. Isn't this how waterfall development was/is supposed to work.
- Ysx 10y agoUnless 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.
- clay_to_n 10y agoBased 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.
- Animats 10y agoOf 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 http://sitetruth.com/doc/sitetruthapi.html
- ktRolster 10y agoHere'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 10y agoCheck out http://apifortress.com/ http://apifortress.com/ I believe they do the exact testing your looking for.
- jamescooke 10y agoLooks interesting! Thanks.
- tmwilder 10y agoYou might find this project interesting: http://swagger.io http://swagger.io We use it to document services by reflecting docs off of the implemented service. Upside, no drift!