Description
Interaction between incorporated software-systems is often realized via application programming interfaces (APIs). The API-documentation explains how to use the API. If it misses important information, serious misunderstandings between the API’s consumer and provider can be the consequence.
I my talk I will show how meaningful names in the source-code can help finding gaps in the API-documentation. My findings base on my project-experiences and a cross-sectional study of a corpus of more than 186.000 web service- operations. I would like to share the 20 description-patterns for API- documentation I found so far. They provide detailed recommendations description of specific operations. The talk closes with a comparison of classical „swagger-like“ API-documentation with the presented approach.