An API is defined through two parts: 1) Machine-readable definitions of the functions and data types used 2) Human-readable explanation of what the previously

An API is defined through two parts: 1) Machine-readable definitions of the functions and data types used 2) Human-readable explanation of what the previously defined functions do when passed each of the allowed data types, with a high-level explanation of how is the API supposed to be used. The first part is usually implemented as part of your programming language - in case of Python, type hints can be used as a substitution. The second part is necessarily informal, since it targets humans. But that does not mean it cannot be well-defined. For example: mmap() creates a new mapping in the virtual address space of the calling process. The starting address for the new mapping is specified in addr. The length argument specifies the length of the mapping (which must be greater than 0). There is no concept of "virtual address space" or "memory mapping" in C. All C knows about is functions and values. But we still know what mmap() does and there is absolutely no ambiguity to its behavior.