-
Right-Size Your RESTful API: More Flexibility Without GraphQL
26 March 2025
Read moreIf you publish a RESTful API and there are situations when you need less (or more!) detail in the API responses from your API - then this post is for you. When I run into this with the teams I advise, the initial problem statement usually arrives more like "We need to move to GraphQL", but this is a solution, not a problem to solve. The problem usually turns out to be either or both of:
the API responses are simply too large for some of the clients or uses cases, users need to select just the fields they want
the API doesn't have enough information in the response payload for this client or use case, users need to choose to include nested data
GraphQL is one way to achieve these things, but this post is about the RESTful way to provide the right level of detail in an API response.
-
Markdown/Mermaid output for OpenAPI Arazzo
12 March 2025
Read moreAPI reference documentation changed the way we built integrations, and eventually became part of the driving force for OpenAPI adoption and all the good tooling that flowed from it. As a developer experience specialist, I spend a lot of time thinking about how human users can work with the technical …
-
From HTTP to OpenAPI with Optic
17 February 2025
Read moreI've been using Optic's CLI, an OpenAPI tool that does a bunch of things including diffing OpenAPI descriptions and comparing HTTP traffic with OpenAPI. My use case was an established API that didn't have an OpenAPI file yet - using Optic we could create one as a starting point, and then move to a design-first workflow to make the changes that I was there to help with. For this blog post, I've used the example of https://api.joind.in as an excellent representation of an API still in use, but without an OpenAPI file and not built with code that a code generator would recognise.
-
Preview OpenAPI as HTML using Scalar
14 February 2025
Read moreThe API DevTools space is alive and well with lots of new and exciting products popping up all the time. I've been especially impressed by the new tools in the docs space, but some of the options are less practical for use as quick human-friendly OpenAPI renderings or previews to use during API development. My current favourite in this space is Scalar because I can get an HTML file to easily include in a build or share with others. It's a bit of a hack though, so I thought I'd share...
-
Presenting with pdfpc
11 February 2025
Read moreMy slide deck tool ( rst2pdf ) produces PDFs, and I use pdfpc to present the PDF slides. It shows the current and next slides, my notes, a timer, and it probably does other things too that I don't use! I've used it for years but it was really designed for "in real world" presenting with one or two screens. Recently I discovered it also supports some great options for remote presentations, but I had to look up how to do that so here are my notes (mostly in case I need to look it up 1 minute before I go on stage again!!).
-
Querying the GitHub GraphQL API
27 January 2025
Read moreIn a recent project around open source contributors, I wanted to take a look at which projects a particular user (actually a few of them, but I wrote a wrapper to repeat the process for each handle) maintains. GitHub doesn't show this maintainer relationship, so instead I used the v4 GraphQL API and looked at pull request comments on repositories that the user has access to. I'm sharing my query and the Python script I used to make the API calls to.
-
Save edits to OpenAPI as an Overlay
09 January 2025
Read moreFor teams that generate OpenAPI from their codebase, there's a tough choice between maintaining rich and extensive content such as Markdown descriptions and examples in codebase annotations, or in making those changes to the generated file - and then losing them when the code changes and the file is regenerated. The new OpenAPI Overlay Specification defines a format for storing updates to an OpenAPI document, and there's a new generation of tools to make it easy to do, so let's take a look.
-
Run GitHub Actions on Subdirectories
07 January 2025
Read moreI come across a lot of "greedy" GitHub Actions, where automation is running across a whole project instead of only on the parts that are relevant. Examples might be code linters that report problems with documentation folders, or the inverse of that. It's especially problematic in monorepos where we probably want to use the same tool when we're doing the same task for different subfolders, but that tool might not make sense to run everywhere.
-
OpenAPI Overlays to avoid API oversharing
12 December 2024
Read moreMost APIs aren't perfect. By design they are long-lived and may serve many audiences. I see a lot of organisations maintaining multiple versions of APIs, or simply not documenting some of the endpoints to avoid them being included in the published documentation and confusing users. The problem of API redaction is a real one in most organisations, and it goes unsolved or is solved in a way that causes ongoing friction. I've helped a few API projects to solve this problem with the new OpenAPI Overlay specification so I thought I'd share!
-
Use multi-line values in GitHub Actions
25 November 2024
Read moreI created an action that needed a rich Markdown value in it, because it's our weekly meeting agenda template which is formatted for humans with links and paragraphs and things. The Action syntax produced errors when trying to add the content directly to the action, but I got it to work by putting the content into the file, and using the file contents as an environment variable. That's really the punchline of this post, but read on if you would like more details and some examples.
-
How to structure and share code examples
18 November 2024
Read moreWriting for technical audiences often means sharing code in one form or another. If the code is only for illustration purposes, then it can be included in the article for observation. But if the code is useful or reusable by your readers, then you need a way to make it available to them. I've seen a few questions on this recently (shout out to the DevRel Collective slack for a brilliant discussion AND nagging me to write it up as a post!), so I'm sharing my experiences on how to publish and maintain code in sane ways!
-
Pretty-print JSON with jq
01 November 2024
Read moreWrangling some document conversion the other day, I ended up in a situation where I had the JSON I needed, but in a completely unreadable format. Luckily, this problem is very easily fixable .... when you know how. So today's post is a quick recap on how I did that using jq, a very handy command-line tool for working with JSON. For the impatient, here's the command: