APIs and JSON

What is an API?

An API stands for Application Programming Interface. The name is intimidating. The idea is not.

An API is just a promise. The server says, "If you ask me a question in this shape, I will send back an answer in that shape." That is the whole contract.

A regular website sends back HTML. HTML is meant for a browser to draw on the screen for a human. An API sends back raw data. Raw data is meant for another program to read and do something with.

Twitter has a website that shows you tweets in a feed. Twitter also has an API that sends those same tweets as plain data to your phone app. Same tweets. Same backend. Just two different ways of asking and answering.

This is how most modern apps are built. One backend exposes an API. Then the website, the iOS app, the Android app, and any other tools that want to use the data all talk to that same API.

REST. The most common style of API

REST is the most common way to design APIs. It is a set of agreements about how URLs and HTTP methods should work.

The idea is that your API is built around things you can act on. Things like users, tweets, orders. You combine the thing with a method to describe the action.

GET /users means "give me all the users." GET /users/42 means "give me user number 42." POST /users means "create a new user." PUT /users/42 means "replace user 42 with this." DELETE /users/42 means "remove user 42."

The URL says what thing you are talking about. The method says what to do with it. If you know the rules, you can usually guess the URL for any action.

REST is not the only way. GraphQL lets the client say exactly what fields it wants. gRPC uses a binary format for speed. But REST is the default because it is simple and works with plain HTTP.

JSON. The shape of the data

When an API answers you, it usually sends back JSON. JSON stands for JavaScript Object Notation. It is just text formatted in a specific way that every programming language knows how to read.

A piece of JSON for a user looks like this: { "id": 42, "name": "Alice", "email": "[email protected]", "verified": true }

JSON only has a few types of things in it. Text in quotes (strings). Plain numbers. The words true and false. The word null for "nothing." Lists in square brackets like [1, 2, 3]. And objects in curly braces with key-value pairs, like the example above.

JSON took over from an older format called XML because it is shorter, easier to read, and easier for code to use. A JSON object is basically the same thing as a JavaScript object, a Python dictionary, or a Go map. So most languages can read and write it without any extra work.

A full example, start to finish

Here is what one API call looks like end to end.

Your app sends: GET /api/users/42

The server replies: 200 OK with the body { "id": 42, "name": "Alice", "joined": "2021-04-15", "posts": 137 }

Your app reads that text, turns it into a usable data structure, and does something with it. Maybe it draws a profile page. Maybe it shows the number of posts on a counter.

What if user 42 does not exist? The server sends 404 Not Found with a body like { "error": "User not found" }. What if you forgot to log in? You get 401 Unauthorized. The pattern is always the same. A status code that says what happened. Plus a JSON body with the details.

Why APIs are everywhere

APIs are the glue that holds modern software together.

The weather app on your phone is calling a weather API. Your bank statement is being pulled from the bank's internal APIs. Your iOS app and your Android app might look totally different but they are both calling the same backend API.

When companies say they have a "service-oriented architecture" or use "microservices," they mean their system is split into many small programs. Each one exposes its own API. They all talk to each other over HTTP.

Once you understand APIs, you can do a lot of things. You can plug your app into Stripe to take payments. You can use OpenAI to add AI features. You can build a mobile app on top of an existing website backend. Pretty much any time one program needs to talk to another, an API is how they do it.