Calling an API from your code

You need tomorrow's weather in your program. You open the API documentation in a browser tab, paste the address, and see a perfectly nice page of JSON. It worked. So you copy that address into your code, run it — and your program crashes with a wall of text. Nothing about the API changed between those two moments. What changed is who was asking.

GET /v1/weather?city=Berlin HTTP/1.1
Host: api.example.org
Accept: application/json


HTTP/1.1 200 OK
Content-Type: application/json

{"city": "Berlin", "tempC": 14}

req:
  GET /v1/weather?city=Berlin

res:
  status = 200
  body.tempC = 14

if (status != 200) -> error
body.tempC

Your browser is a program that does a lot of extra work on your behalf, silently. It stores cookies so you stay logged in. It follows redirects and shows you the final page without mentioning the three hops it took. It retries when a connection drops. It runs the JavaScript that a modern site needs in order to show anything at all. And when it gets a 404, it cheerfully draws a nice error page, so the request looks like it succeeded. Your program does none of that unless you write it. A status code of 404 is not an error page to your code — it is a number you must check, and if you do not check it, you will happily try to read weather data out of an error message.

There is one more family you will meet constantly in real code: 3xx. A redirect is the server saying “not here, look over there”. A browser follows it for you and you never notice. Your HTTP client may or may not, depending on how it is configured, and the answer changes which data you end up with.

A timeout says: I will wait this long for an answer, and then I stop and treat it as a failure. Without one, your program waits forever on a server that is never going to reply — the button spins, the request never finishes, and the user has no idea what is happening. Two seconds is a normal choice for a request a person is waiting for. The important consequence is that a timeout is not proof that the request did not happen: the other side may have received it and done the work, and only the answer got lost on the way back.

So a sane payment flow looks like this: give each attempt a unique key, send it with the request, and give the request a timeout. If the request times out, send it again with the same key. If the money already moved, the other side recognises the key and tells you so instead of charging again. You also never retry forever: a couple of attempts with a growing pause between them, then give up and tell the user honestly.