Introduction
An API, application programming interface, is a defined set of rules that lets one piece of software request functionality or data from another without needing to know how that other software is built internally. It specifies what requests are allowed, what information each request needs, and what response to expect back, acting as a contract between the two sides so they can change their internal implementation independently as long as they both honor that contract.
Cricket analogy: A stadium's hospitality-booking desk lets a corporate client request a box for a match without needing to know how the catering or seating logistics work behind the scenes, as long as the client fills in the required booking fields and gets a confirmation back, exactly like an API's request-response contract.
Explanation
The most common style of web API today is REST, which uses standard HTTP methods to express what kind of operation is being requested: GET retrieves data without changing anything, POST creates a new resource, PUT or PATCH updates an existing resource, and DELETE removes one. Resources are identified by URLs, so a request like GET /users/42 asks for the user with ID 42, while POST /users creates a new user from the data included in the request body.
Cricket analogy: A cricket board's public stats portal exposes GET /players/42 to retrieve player 42's record without changing anything, POST /players to register a brand-new player from submitted data, and PUT /players/42 to update that player's existing record, mirroring how REST maps HTTP methods to operations on a URL-identified resource.
Most public APIs require authentication, commonly through an API key or a token sent in a request header, so the server can identify who is making the request and enforce rate limits or permissions. Responses typically use a status code to indicate the outcome: 200 means success, 201 means a resource was created, 404 means the requested resource doesn't exist, and 401 or 403 mean the request lacked valid credentials or permission.
Cricket analogy: A cricket board's data feed requires a partner's access token in every request header so the board knows which broadcaster is asking and can cap how many requests they make per minute, and it replies with 200 for a successful lookup, 201 after registering a new fixture, 404 if a requested match doesn't exist, and 401 if the token is missing or invalid, mirroring API authentication and status codes.
GET /users/42 HTTP/1.1
Host: api.example.com
Authorization: Bearer <token>
# Successful response
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 42,
"name": "Ada Lovelace",
"email": "[email protected]"
}
Example
A weather app on your phone is a good everyday example: the app itself doesn't run weather sensors or satellites, it sends a GET request like GET /forecast?city=Boston to a weather provider's API, receives back a JSON response with the temperature and forecast, and displays that data. If the weather provider changes its internal database or server technology tomorrow, the app keeps working exactly the same as long as the API's request and response format stays the same.
Cricket analogy: A fan's cricket-scores app doesn't run its own scoreboards at every ground, it sends a GET request like GET /matches?team=India to a scoring provider's API, receives back structured data with the current score, and displays it, and the provider can rebuild its internal scoring system entirely without the app noticing, as long as the API contract stays the same.
Analysis
APIs are typically versioned (for example, /v1/users versus /v2/users) precisely because the contract sometimes must change in incompatible ways; consumers relying on undocumented behavior rather than the documented contract risk breakage even when the version number doesn't change.
Key Takeaways
- An API is a defined contract that lets one piece of software request functionality or data from another without knowing its internals.
- REST APIs map HTTP methods (GET, POST, PUT/PATCH, DELETE) to operations on resources identified by URLs.
- Authentication, usually via an API key or token in a request header, identifies the caller and enables rate limiting and permissions.
- Status codes summarize the outcome: 200 success, 201 created, 404 not found, 401/403 unauthorized or forbidden.
- As long as both sides honor the API contract, either side's internal implementation can change without breaking the other.
Practice what you learned
1. What does an API primarily define?
2. In REST, which HTTP method is used to retrieve data without changing anything?
3. What is the purpose of an API key or token sent in a request header?
4. What does an HTTP 404 status code indicate?
5. Why can a weather app keep working even if the weather provider rebuilds its internal backend?
Was this page helpful?
You May Also Like
What Is OOP
An introduction to object-oriented programming, covering classes, objects, encapsulation, inheritance, and polymorphism.
What Is JSON
An introduction to JSON's syntax and data types, and why it became the standard format for exchanging structured data between systems.
Reading Documentation
A practical guide to reading technical documentation efficiently, covering reference docs, signatures, examples, and changelogs.
Related Reading
Related Study Notes in Programming
Browse all study notesApache Spark Study Notes
Programming · 30 topics
ProgrammingApache Flink Study Notes
Programming · 30 topics
ProgrammingHadoop Study Notes
Programming · 30 topics
ProgrammingSnowflake Study Notes
Programming · 30 topics
ProgrammingApache Airflow Study Notes
Programming · 30 topics
Programmingdbt (Data Build Tool) Study Notes
Programming · 30 topics