Where to find APIs?

• Operating Systems
• Programming Language Runtimes
• Hardware Access
• User Interfaces
• Databases
• Web and Cloud Services

Operating Systems

• Win16, Win32, Win64
• POSIX
• Cocoa (OS/X)
• android.os

Hardware Access

Abstractions to program any kind of hardware device

• Graphics (OpenGL, WebGL, OpenCL, CUDA)
• Network (NDIS)
• Printers (CUPS)
• Device Drivers (WDF, I/O Kit)

Databases

Standardized database access

• JDBC
• ODBC
• PHP PDO

API Evolution

• Once in the API, keep it there forever
  • Never add something you do not intend to keep forever
  • Easier to add than to remove
• Keep changes backwards and forwards compatible
• Make sure you explicit version all changes (including documentation) pointing out incompatibilities
• Publish 0.x versions of an API before freezing it to get early feedback from users
• Rename a component if its API has changed too much so you can start the redesign from scratch without breaking old clients

API Compatibility

• Backwards compatibility:
  new version of API compatible with old client
• Forwards compatibility:
  old version of API compatible with new client

3 Versions Rule

Claus Hagen

Up to 3 versions of an API exist at the same time:

• Legacy v1.0: migrate old clients
• Current v2.0: normal operation
• Future v3.0: develop new experimental clients

Before v4.0 can be added, v1.0 needs to be retired

1435mm Standard Gauge
1668mm Iberian Gauge
1524mm Russian Gauge
1000mm RhB (Swiss Alps)

Compatible Interfaces

• To be connected, component interfaces need to match perfectly

Adapter

• Adapters help to connect mismatching interfaces
• Adapters deal with transforming the interaction provided by one to the interaction required by the other interface
• Warning: if data or functionality are missing the adaptation may be impossible

Wrapper

• The mismatching end of the adapter is hidden inside a wrapper component
• The adaptation logic is encapsulated within the wrapper and made reusable

Mismatch Example

A
id upload(user, image);
image download(id);
setTitle(id, title);
title getTitle(id);
ids[] list(user);

B
id upload(user, image, title);
{user, title, time} getImageMetaData(id);
image getImageData(id);
ids[] list();

Are Interfaces A and B equivalent?