Tukuk-OSBefore I understood HTTP, I saw 404 and 500 as mysteries. After understanding them, I realised the whole web is just text sent back and forth with clear rules. HTTP is the language I had to master to make Tukuk-OS communicate with the outside world.
Request and Response: One Exchange
Every time you open a page, your browser sends a request and the server sends a response. A request contains a method (GET, POST), a path (/search), headers, and sometimes a body. A response contains a status code, headers, and content.
The first thing I learned is that GET should not change anything, while POST sends data to be processed. At first I used GET for everything including my contact form, until I realised that long questions end up in server logs and browser history. This division is not decoration — it is the foundation of security and privacy.
Status Codes: Honest in Three Digits
I memorised five status codes before any terminal command:
- 200 OK — everything is fine.
- 301 Moved Permanently — the address has moved.
- 400 Bad Request — your request is wrong, not the server.
- 404 Not Found — the resource does not exist.
- 500 Internal Server Error — the server has an internal problem.
In Tukuk-OS I treat these codes carefully. When the NASA APOD endpoint fails I return 500 with a clear message, not 200 with empty content. My clients (the web pages) then know to retry or show the right error message. Honesty in status codes produces better interfaces.
Designing APIs: Names That Speak for Themselves
My first API was full of paths like /getdata and /process. I then learned that a good path describes a resource, not an action: /api/nasa/apod, /api/nasa/asteroids, /search, /blog/:slug. With that structure a client can guess a route it has never seen.
I also learned to wrap responses in a consistent shape: success returns the data directly, failure returns { "error": "..." }. This consistency let me write client code once and use it for every endpoint.
My First API Design Mistake
My first API had a structural problem I did not notice until I tried to build a second client: every route returned a different data shape. One route returned a list directly, another wrapped it in an object with a data key, and a third returned a single object even though results were always a list.
As a result my client code was full of special cases — "if the response is a list, do this; if it is an object, do that". Every new route added a new branch. After a few months I rewrote every route to follow a single convention: lists always arrive as lists, objects always as objects, and errors always carry the same error key.
That rewrite took two days and removed about a hundred lines of special-case handling from my client. The lesson that lasts: conventions beat flexibility. When every route looks and behaves like the others, you can write generic code that works with all of them at once — and that is the foundation of the entire Tukuk-OS API layer today.
Query Parameters and Filtering
?q=nasa&limit=20&offset=0 — query parameters became how I filter results. In Tukuk-OS almost every search endpoint accepts q, limit, offset, plus filters like host, lang, and type. I learned that every parameter I add needs a sensible default so the simplest possible call still works.
Calling External APIs: A World That Is Not Perfect
When I started calling the NASA API I learned that networks cannot be fully trusted. Requests can time out, servers can fail temporarily, and responses can arrive unlike what you expected.
My biggest lesson here is the circuit breaker. When the NASA APOD endpoint starts returning errors repeatedly, I do not want every client waiting thirty seconds for a timeout. I record "this service is failing right now" for ten minutes, then simply use the fallback. That pattern has saved the Tukuk-OS user experience repeatedly.
HTTP/1.1, HTTP/2 and HTTP/3
Even though I do not write the protocol myself, understanding the differences helps me make configuration decisions. HTTP/2 allows many requests on a single connection, while HTTP/3 (QUIC) reduces connection start latency. When I enabled HTTP/2 behind Cloudflare, Tukuk-OS pages downloaded in parallel instead of sequentially, and the difference was noticeable on slow connections.
What This Means for Tukuk-OS
Tukuk-OS today is a large set of APIs: search, suggestions, images, videos, NASA data, contact forms, and statistics. Each of them respects the HTTP rules I learned in the early days: correct methods, honest status codes, consistent response shapes, and errors that can be acted upon. Not everything I know about the web came from books; most of it came from seeing a 500 on my own screen and asking why.