3 The API: Let’s talk

Communicating with people through the spoken and written word, gestures, expressions, and inflection is one of the cornerstones of our advancement as a species. Even across different languages and cultures, we can communicate with each other, perhaps with a bit more effort, but we can learn to convey meaning, intent, information, goals, and more.

The evolution of computers has also created many and varied ways for us to communicate with a computer, and it with us. Keyboards, mice, touchpads, voice, screens, printers, networks, motion sensors, and more are all devices that have different uses for providing communication between people and computers.

All these devices are examples of interfaces designed to convey information to and from a computer system. Keyboards provide a mechanical way for us to enter the written word into a system. A computer mouse provides one way to indicate gestures and events to a computer system. A display screen provides a way for the computer to represent digital information so we can receive it. Speakers give a computer an interface to produce audio information.

All the complexities of capturing a keystroke, positioning the mouse pointer on the computer display, or generating a sound from a computer are simplified, hidden, and provided by the interface.

3.1 Starting a conversation

3.1.1 A contract between pieces of code

3.1.2 What’s passed as input

3.1.3 What’s expected as output

3.2 Function API

3.2.1 Naming

3.2.2 Parameters

3.2.3 Return value

3.2.4 Single responsibility

3.2.5 Function length

3.2.6 Idempotence

3.2.7 Side effects

3.3 Documentation

3.4 Closing thoughts