Earlier today I posted on Bluesky:

"I remember when there were only four kinds of HTTP requests and nobody used any but the first two."

My spouse read that and said "Feeling old, dear?"

No, not exactly. I mean, valid; there are all kinds of things every day now that make me feel old. But this was more like "I'm not sure what the point is here."

This was brought about because I spent the day writing code to use someone else's API -- a new piece of software at $EMPLOYER that I need to be able to pull data from on a nightly basis. And I hasten to add, it's a good API. It's well designed and it is exceedingly well documented. The documentation is absolutely first rate. The kind of docs I've pretty much given up on ever finding; nobody bothers to do it this well anymore.

(My own documentation tends to be pretty good -- when I have time to do it. It's always the lowest priority and it's constantly getting bumped in favor of more urgent things.)

Anyway, I can't explain this like you're five -- it's not possible -- which means that for about seven out of ten people who read this it'll be incomprenhensible. But I'll try.

There are only a handful of HTTP requests and there are really only two ways to do them -- GET style and POST style.

A GET style request looks like this:

We'll get to see if my monospace card can handle that. I can't preview this before I post it. It'll be a surprise. I don't know if I've used the mono card before this.

Anyway, that's all supposed to be one line -- one URL. The question mark separates the command path from any arguments; the ampersand separates arguments. There's supposed to be a line limit (I was taught that a GET URL couldn't exceed 255 characters, though for all I know that may have been hallucinated), but no standard has never been enforced, which aggravates the shit out of me because you see people having thousand-character GET URLs ... which means they should be doing a POST but either they don't know how or they think GETs offer more "transparency."

See, in a GET request you can see all of it because it's all out there in the URL. A POST request has just the path to whatever you're talking to; all the parameters and so forth are contained in a content block which is sent separately. So it's hidden. Actually it's not very hidden, and anybody who knows what they're doing can see what's in the content body. But it seems hidden to everybody else. The advantage, of course, is if you're trying to post bigger lumps of data -- like, say, the contents of this entry, which will be sent to my receiving code via POST method when I press the -30- button at the bottom of the page -- it doesn't clutter up the place with a 5000-character GET line and also you don't have to "escape" special characters the same way you would there. If you've ever wondered about all those %20s and other things like that in a GET line, it's because a lot of characters are illegal in a URL. %20 is a space. No, you can't have spaces in a URL. They'll break.

Anyway, to recap: A GET request sends all the goodies right there in the URL; a POST request sends most of them separately in a content block. GET is for short easy requests with a couple of parameters; POST is for posting big globs of stuff.

Two other HTTP request types, PUT and DELETE, have been around since the early days. PUT works exactly the same way as POST, and DELETE was supposed to work the same way as GET but some people try to shove a content block into it anyway. But the point is, those variations mean very little because you're either sending a request GET style or POST style, no matter what you call it. I didn't use PUT or DELETE for years and years. Most of the code I was talking to didn't care either.

The problem is, some people liked that there was a kind of symmetry between these request types and what is unfortunately often referred to as CRUD. The four basic types of data instructions: Create, Retrieve, Update, and Delete. I have been working in SQL since before some of you were born so I prefer SELECT, INSERT, UPDATE, and DELETE but I admit it's hard to come up with a catchy acronym from those ... and also apparently there are a lot of people who have never understood why SELECT is called that. Those people should probably not be allowed to be programmers.

Anyway, somebody looked at GET (retrieve), POST (insert/create), PUT (update), and DELETE and said "Hey, it's just like CRUD!" This is a bad way to think. Even the Mozilla Developer Network pages (and honey, if you're looking up something having to do with HTTP or HTML there is no more reliable source extant at this time) cautions against getting overmuch in this mindset.

And now to the actual point of the story: Today, for the first time, I encountered an API that actually used the PATCH request. (This is not just me. I told my co-worker in Slack and she responded, and this is a direct quote: "I thought PATCH was imaginary.")

But the MDN says, no, it's real, and furthermore, there's a distinction. The MDN says that PATCH is to be used when you have incremental/partial updates to a data block. PUT, they insist, should properly be reserved for "replace the whole damned thing." PUT is for when you want to completely overwrite whatever data record you're writing with your new stuff. PATCH is for when you want to maybe change one or two little bits of the data and leave the rest intact.

News to me -- but, as I say, we do not argue with the MDN in this house.

Soooo this API uses PATCH for record updates, where I would normally have used PUT, and they reserve PUT for uploading/sending blobs -- big gooey chunks of non-human-readable binary data. Specifically, in this case -- this is a personnel tracking system -- people's profile images and PDFs for their CVs. Neither of which I will be sending or retrieving, so I need not bother with PUT. Nor with DELETE, which they use only for said blobs. (They don't provide a DELETE method for structured data at all ... they don't want you deleting any of it, which is very common in large-database applications. Leaves holes. Stranded references, mostly, where some other record says "See this record" and the record it's telling you to see no longer exists. Better to mark a record as inactive or obsolete than to delete it outright.)

Actually, I'm using this API on a read-only basis and I'm only using one of its methods, so I really will never need to bother with anything but GET and this is all academic. But it does mean I went to the MDN and learned about request types like HEAD and OPTIONS and TRACE which I have never seen before in my life.

I'm sure there's a good use case for each and every one of them. But I just want you all to know that you can still do everything you want with GET and POST, no matter what anyone tells you.

I'm on staycation all of next week, and I finished the August story (a Coldpoint) two days ago, so I'm kind of at leisure for a bit. I may do a couple of teeny tiny things next week -- I'm talking the kind of futzing around that takes maybe an hour or two at most. Or I may just spend all my free time next week playing escape rooms. I don't know. I don't plan to know in advance. It'll happen as it happens.