Understanding APIs
At a Rainkit workshop, a student raises her hand: "Everyone keeps saying 'just call the API'. What does calling it actually mean?" Rainkit is an API, so Meera needs to be able to explain one to anyone, from first principles, in two minutes.
The rule
An API is a promise: send this request, get that response.
An API (application programming interface) is how one program asks another for something. A web API does it over HTTP. The provider promises: if you send a request shaped like this, you will get a response shaped like that. Here is one call to Rainkit:
curl "https://api.rainkit.example/v1/forecast?lat=18.52&lon=73.86&hours=3" \
-H "Authorization: Bearer rk_test_123"And the reply:
{
"location": { "lat": 18.52, "lon": 73.86 },
"hours": [
{ "time": "2026-07-14T15:00:00+05:30", "rain_chance": 0.82, "rain_mm": 4.1 },
{ "time": "2026-07-14T16:00:00+05:30", "rain_chance": 0.64, "rain_mm": 1.8 },
{ "time": "2026-07-14T17:00:00+05:30", "rain_chance": 0.21, "rain_mm": 0.0 }
]
}Every web API call has the same five parts:
- Method: what kind of action.
GETreads,POSTcreates,DELETEremoves. - Path: which resource.
/v1/forecast, wherev1is the version of the promise. - Parameters: the details of the request:
lat,lon,hours. - Credentials: who is asking. Here, an API key in the
Authorizationheader. - Response: a status code and a body, usually JSON.
Status codes come in families. 2xx means success (200 OK). 4xx means the caller must change something: 400 is a bad parameter, 401 a missing or invalid key, 404 a path that doesn't exist, 429 too many requests. 5xx means the problem is on the server's side, such as 500 or 503.
Why call it a promise? Because thousands of apps are written against it. If Rainkit renamed rain_chance tomorrow, every one of those apps would break. That is a breaking change, and it belongs in a new version, /v2/, while /v1/ keeps its promise.
The shortcut
Read any call as method, path, parameters, credentials, response. For errors, look at the first digit: 4 means fix your request; 5 means it's the server.
Method
GET: we are reading data. Nothing changes on the server.
Drills
Answer fast — trust the rule.
A request returns 401. What is most likely wrong?
A script gets 429 after looping over 2,000 locations. What does it mean?
Which HTTP method fits registering a new webhook with Rainkit?
Rainkit's team wants to rename rain_chance to probability. Why is this risky?
During a Rainkit outage, requests return 503. Where is the problem?
Remember
- An API is a promise: send this request, get that response.
- Shortcut: method, path, parameters, credentials, response. 4xx means fix your request; 5xx means the server.
- Trap: changing a response's shape without a new version breaks everyone who relied on it.