Writing better API documentation: a few lessons from enterprise integration
Jun 29, 2022
Over many years working on API integrations, I’ve seen a whole lot of ways that the experience could be less frustrating. This isn’t a definitive list but a personal collection of a few recurring problems with documentation I’ve seen in different REST APIs that could be avoided.
Explain what a field does
Consider API documentation like this:
String[] tags - “This field contains tags for the post.”
This is not helpful.
...
➦
Possible vulnerability in Sainsbury's and Nectar website
Mar 16, 2022
In February, I discovered a potential vulnerability in the Sainsbury’s and Nectar website. Sainsbury’s is one of the UK’s main supermarkets, and Nectar is the loyalty card programme they own in partnership with a bunch of other retail brands like Argos, Esso and British Airways.
The vulnerability is not that exciting and I have no way to know whether it is possible to misuse it without breaking the Computer Misuse Act 1990, which I obviously don’t want to do.
...
➦
iTerm2 URL matching is pretty neat
Mar 20, 2021
For many years, other developers told me about iTerm2 and I ignored them. I really shouldn’t have. The stock macOS Terminal was fine, I thought. What a mistake.
There’s lots to love about iTerm2, including the ability to script it in Python. But a really amazing quick win is the support for Triggers. Triggers allow you to set a regular expression that gets acted on every time they appear in the terminal.
...
➦
Too sarcastic for the Twitter joke police: an adventure in automated moderation
Feb 18, 2021
In which computers built by Silicon Valley-funded companies fail to get British humour.
...
➦
Never trust a Time Machine made by a computer company
Dec 31, 2020
In which Apple makes me very, very weary.
...
➦
Using AST parsing for deriving IAM rules
May 19, 2020
With enough metaprogramming, security can be fun.
...
➦
That's not what the law says: the coronavirus regulations
Apr 08, 2020
If you want a rule of law, maybe read the law?
...
➦
Hart contracts, not smart contracts
Feb 06, 2020
Why a philosophical argument shows the folly of Smart Contracts
...
➦
The NHS Data Commandments and the memory hole
Feb 04, 2020
Back in 2018, the British government published a document on the World Wide Web. This happens fairly often. In fact, they have a whole publishing platform for this. I started writing a post critiquing this document, as I felt it was a poorly considered idea. Before I got around to publishing it, the document disappeared from the Internet. Life went on. I was busy, and there are always many more blog post drafts that don’t ever get written or published.
...
➦
Essential reading on the MIT Media Lab
Sep 08, 2019
A peek inside the embattled Media Lab.
...
➦