Application programming interface - API Types and Design Principles

Types of Application Programming Interfaces Introduction An Application Programming Interface (API) is a contract between different software components. It specifies how one piece of software can interact with another—what requests it can make, what responses it will receive, and what behavior to expect. Think of an API as a standardized menu at a restaurant: customers don't need to know how food is prepared in the kitchen; they just order from the menu and receive the expected dish. APIs come in several forms, each solving different problems in software development. Understanding these different types will help you recognize which type of API you're working with and anticipate how to use it effectively. Library and Framework Interfaces The most direct type of API is the library interface—the set of functions, classes, and methods that a software library exposes to developers. When you use a library, you're interacting with its API. A key principle in API design is the separation between specification and implementation. The specification describes what the API promises to do: what parameters it accepts, what it returns, and how it behaves. The implementation is the actual code inside the library that makes it work. This separation is important because it means: Different libraries can implement the same API specification in different ways A developer can switch between implementations without changing their code, as long as both implementations follow the same specification For example, there are multiple database libraries that implement similar APIs for accessing data. A program written to use one library's API might be able to switch to another library's implementation without requiring code changes. Language bindings extend this flexibility further. A library might be written in one programming language (like C), but developers using other languages (like Python or Java) need a way to access it. Language bindings are adapters that map the API's features from one language into another language's syntax and conventions. This allows cross-language reuse of a single library. Operating System Interfaces Operating systems also provide APIs that allow applications to request services—things like reading files, allocating memory, or managing processes. These OS-level APIs define how an application communicates with the operating system kernel. POSIX (Portable Operating System Interface) is a standardized set of API specifications that many operating systems follow. By adhering to the POSIX standard, operating systems ensure that programs written to the POSIX API can run on different operating systems with minimal or no changes. This portability was crucial in the Unix ecosystem and remains important today. A good example of OS API design with different goals is Microsoft's Win32 API (the Windows API). Win32 was specifically designed with backward compatibility in mind. When Microsoft released new versions of Windows, they ensured that Win32 APIs continued to work exactly as they did before. This meant older applications could keep running on newer Windows versions without modification—a significant advantage for users with legacy software, though it sometimes locked in design decisions that later became challenging. API vs. ABI: An Important Distinction You'll encounter the term Application Binary Interface (ABI), and it's easy to confuse it with API. Here's the crucial difference: An API is source-code based. It defines what a programmer writes in code. It's language-focused and describes the contract in terms a programmer understands. An ABI is binary-code based. It defines how compiled machine code interacts with other compiled code. It's lower-level and describes memory layouts, calling conventions, and binary formats. Think of it this way: two libraries might have identical APIs (same function names and parameters), but different ABIs (different binary layouts). A program compiled against one library's ABI might not work with another library's ABI, even if their APIs are identical. Remote Application Programming Interfaces The APIs discussed so far have been local—the application and the software it's accessing are on the same machine. Remote APIs, by contrast, allow a program to manipulate resources and call functions on remote machines through standardized protocols. Java Database Connectivity (JDBC) Java Database Connectivity (JDBC) is a remote API that solves a practical problem: applications need to query different types of databases (PostgreSQL, MySQL, Oracle, etc.), but each database has its own native protocol. Rather than forcing programmers to learn each database's specific protocol, JDBC provides a standardized API. A program written using JDBC can connect to different databases; only the database driver (the library that implements the JDBC API for a specific database) needs to change. Java Remote Method Invocation (RMI) Java Remote Method Invocation (RMI) solves a different problem: making remote method calls appear as if they're local. Without RMI, calling a method on a remote machine requires the developer to explicitly handle network communication, serialization of data, and error handling across the network. RMI abstracts these complexities away—a developer can write code that looks like calling a local method, and RMI handles all the network communication behind the scenes. Web Application Programming Interfaces As the web became dominant, a new type of API emerged: the Web API. These APIs define how external applications can interact with a web service to access its data or functionality. They're crucial to modern software development because they enable different services to work together. Structure and Communication Web APIs typically operate over HTTP (the protocol that powers the web) and define two key elements: HTTP Request Messages: What the client (the application using the API) needs to send. This includes specifying which resource to access and what action to perform. Response Structure: The format of the data returned by the server. Most modern web APIs use JSON (JavaScript Object Notation) or XML (Extensible Markup Language) to structure their responses. RESTful APIs Traditional web APIs often used SOAP (Simple Object Access Protocol), a more complex protocol for remote procedure calls. RESTful APIs emerged as a simpler alternative that leverages HTTP itself more directly. RESTful design uses: HTTP verbs to indicate what action to perform (GET to retrieve data, POST to create, PUT to update, DELETE to remove) Resource-oriented URLs that identify what you're acting on (like /users/123 to reference user with ID 123) This approach is simpler and more intuitive than SOAP-based protocols, which is one reason RESTful APIs became dominant. Mashups Web APIs enable a powerful pattern called mashups: combining multiple APIs into a single new application. For example, a real estate website might combine a mapping API with a property database API and a mortgage calculator API to provide a comprehensive service. Neither the mapping service nor the property database is designed specifically for real estate—but their APIs are flexible enough to enable this new application. Design Principles for APIs Beyond the different types of APIs, certain design principles influence whether an API is useful and widely adopted. Minimal Exposure Minimal exposure means an API should provide only the tools developers expect and need, avoiding unnecessary complexity. Every feature you expose in an API creates additional complexity: more to document, more to test, more for developers to learn, and more potential sources of bugs. Good API design requires restraint. Just because your library can do something doesn't mean it should expose that capability through the API. Ask: will developers actually need this? Can they achieve their goals without it? If not essential, keep it hidden in the implementation. Impact on Usage The design of an API significantly influences how frequently and effectively developers use it. A poorly designed API frustrates developers, leads to bugs, and may be abandoned in favor of alternatives. By contrast, an elegant API that's intuitive and does what developers expect becomes widely adopted and enables innovation. This is why API design is not just a technical detail—it directly affects whether your software will be successful and widely used. <extrainfo> Additional Context The images in the source material show examples of modular design (building blocks can be assembled in different ways) and historical computing infrastructure. These illustrate the principle that APIs are fundamental to letting different components work together flexibly—whether in LEGO® blocks or in enterprise systems spanning multiple computers. </extrainfo>