What an API actually is

Three ways to see it

1. 1

   API stands for Application Programming Interface, but the words obscure rather than explain. Think of an API as a menu at a restaurant. The kitchen can produce hundreds of dishes, but the menu lists what you are allowed to order, how to order it, and what you will receive in return. You do not walk into the kitchen and demand the chef cook however you like. You point to a line item on the menu, say the words exactly, and a plate arrives. The menu is the contract. The kitchen is the system behind it. The waiter is the network. An API is a published menu plus the promise that the kitchen will honour every line on it.

2. 2

   Take a concrete Pakistani example. NADRA exposes a verification API to authorised banks and telecom operators. When you open a new account at Meezan Bank or activate a Jazz SIM, the agent enters your CNIC and thumbprint into a terminal. That terminal sends a request to NADRA's API: 'here is a CNIC number and a biometric, please confirm the identity.' NADRA returns yes or no with a confidence score. The bank never sees NADRA's internal database. The bank only sees what the API agreed to share. The contract protects both sides. NADRA controls what leaks out. The bank gets exactly what it needs.

3. 3

   Three components define every API. First, the endpoint, which is the address you send your request to, like https://api.nadra.gov.pk/verify. Second, the request shape, which is the exact data the endpoint expects, often a CNIC, a thumbprint, and your authorisation key. Third, the response shape, which is the exact data you get back, often a status, a confidence score, and an audit reference. Change any of the three without notice and every consumer of the API breaks. This is why API contracts are versioned and why the discipline of API design matters more than the code behind it.

The why-tree

Try this with Claude

AI-edge prompt to try with Claude or ChatGPT: 'I work in the FBR's policy wing. List five public APIs that other Pakistani government departments expose today, what each one returns, and one concrete way the FBR could use each of them in a citizen service. Cite official URLs.' Compare the answer to the survey you will see in lesson 7.