What an API Actually Is
An Application Programming Interface (API) is a defined contract that specifies how one piece of software can request services or data from another, and what it will receive in return. The API is the interface — the agreed protocol for communication — not the implementation. The weather API that returns current temperature and forecast data does not care what programming language the application requesting the data is written in, what operating system it runs on, or how it will display the data; it cares only that the request follows the specified format and that the response follows the specified structure. This abstraction — the separation of interface from implementation — is what makes APIs the most powerful architectural pattern in modern software development.
The API economy concept that most accurately describes how modern software ecosystems are built: the practice of building software by composing capabilities from multiple specialised APIs rather than building every capability from scratch. The startup that needs payment processing uses Stripe’s API; the one that needs mapping uses Google Maps’ API; the one that needs authentication uses Auth0’s API; the one that needs email delivery uses SendGrid’s API. Each of these capabilities took their respective companies years and enormous resources to build; the startup accesses each of them in minutes by reading the API documentation and making the specified API calls. The API economy has dramatically reduced the time and cost required to build software applications by making previously hard-to-build capabilities available as composable services.
REST APIs: The Dominant Architecture
The REST (Representational State Transfer) architectural style, first described by Roy Fielding in his 2000 doctoral dissertation, has become the dominant approach to building web APIs because it aligns naturally with the HTTP protocol that the web was built on and because its conventions are simple enough to be quickly understood by any developer familiar with web development. A RESTful API organises its functionality around resources (the nouns — users, products, orders, messages) and uses standard HTTP methods (GET to retrieve, POST to create, PUT/PATCH to update, DELETE to remove) to specify what operation is being performed on a resource.
The REST API design principles that most determine whether an API is pleasant to work with or frustrating to use: consistent resource naming (using lowercase nouns in plural form for resource collections — /users, /products, /orders), appropriate use of HTTP status codes (200 for success, 201 for created, 400 for bad request, 401 for unauthorised, 404 for not found, 500 for server error — rather than returning 200 OK for all responses and encoding success or failure in the response body), and clear error response format (providing specific, actionable error messages rather than generic error codes that require the developer to consult separate documentation to understand).
GraphQL: When REST Is Not Enough
GraphQL, developed by Facebook and open-sourced in 2015, was designed to address specific limitations of REST that become most problematic in complex, data-intensive applications: the overfetching problem (REST endpoints return fixed data structures that may include far more data than the client needs, wasting bandwidth and processing), the underfetching problem (a single REST endpoint may not include all the data a client needs, requiring multiple requests to assemble a complete view), and the versioning problem (adding new fields to a REST API or removing obsolete ones requires careful version management that becomes increasingly burdensome as the API evolves).
The GraphQL characteristics that most determine whether it is the right choice for a specific use case: it is most valuable for applications with complex, interconnected data models where different clients need different subsets of the same underlying data (a mobile client that needs minimal data and a web client that needs comprehensive data can both be served from the same GraphQL API, each specifying exactly what data they need), and for applications where the development team controls both the API and its clients (which allows the schema to evolve based on what the clients actually need). It is less valuable for simple data access patterns, for public APIs where the client population is unknown, and for teams without GraphQL expertise.
Authentication and Security in APIs
The API authentication mechanisms that most commonly protect production APIs: API keys (simple tokens that identify the calling application — suitable for server-to-server communication where the key can be kept secret, but not for client-side code where the key would be visible), OAuth 2.0 (the standard protocol for delegated authorisation, where users grant applications access to their data with defined scopes and without sharing their credentials — the mechanism behind Sign in with Google, Log in with GitHub, and similar authentication flows), and JSON Web Tokens (JWTs, which are signed tokens that encode claims about the authenticated user and can be verified without a database lookup, making them efficient for stateless authentication in distributed systems).
The API security vulnerabilities that most commonly appear in production API implementations: broken object-level authorisation (the API that returns data for any resource identifier provided in the request without verifying that the authenticated user has permission to access that specific resource — allowing an attacker to access other users’ data by substituting their resource ID), excessive data exposure (the API that returns full object representations including sensitive fields that should not be exposed — requiring clients to filter the data they actually need), and broken function-level authorisation (the API that fails to check whether the authenticated user has permission to invoke a specific function, allowing low-privilege users to access administrative functions).
Building and Consuming APIs Effectively
The API development practices that most improve the quality and maintainability of APIs over time: the API-first design approach (designing the API contract before implementing it — which forces explicit decisions about the interface that implementation-first approaches tend to defer until they are already constrained by implementation choices), the OpenAPI specification (the standard format for documenting REST APIs that enables automatic generation of client SDKs, interactive documentation, and API testing tools), and the versioning strategy (the pre-planned approach to introducing breaking changes in a way that allows existing clients to continue working while new clients adopt the updated API — typically implemented through URL versioning (/v1/, /v2/) or header versioning).
The API consumption practices that most improve the reliability and maintainability of applications that depend on third-party APIs: the abstraction layer that wraps the third-party API behind an internal interface (which allows the third-party implementation to change or be replaced without requiring changes throughout the codebase), the retry logic with exponential backoff (which handles the transient failures that any network-dependent call will periodically experience, without the retry storm that naive retry implementations can cause), and the circuit breaker pattern (which prevents a failing third-party API from causing the entire application to fail by detecting failure patterns and temporarily stopping calls to the failing service).