Tag Archives: api

12 Dec
2024

OpenAPI Overlays to avoid API oversharing

Most 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! Continue reading →
09 Oct
2024

Open Standards for APIs

I work or have worked with APIs of all sorts of standards, sometimes many standards at once – or none. Each standard exists for a purpose and might be a great fit, or a terrible fit for other purposes. Today’s post is a recap of some of the common API standards around and what you need to know about each one. Continue reading →
18 Jun
2024

API Description Pipelines

Working on API tools, I get to see inside lots of different organisations’ API projects and processes. Every scenario is different, but a common theme is that many companies use a more complicated API description workflow than you see in conference slide decks! Without sharing any one organisation’s secrets, this article shares a rundown of some typical steps that might show up in an API description pipeline. Continue reading →
11 Jan
2024

API Linting Levels

I’ve been thinking about API linting lately, partly because I work on a tool for API linting in my day job, and partly because I get quite a lot of questions from teams wanting to improve their API quality. The “best” ruleset depends entirely on your context, where you are in your API practice journey, and how much you want to invest in the API in question. I typically use a 4-levels model of API linting readiness, and I’m sharing them so that you can find yourself on the map and see where you might go from here. Continue reading →
28 Nov
2023

Add OpenAI flags to OpenAPI descriptions

With OpenAI’s new Actions feature allowing you to get a GPT that uses your own API, many new doors are open. However giving an AI an access token the keys to your API and telling it to have fun may lead you to realise that one of the doors available leads to the empty lift shaft of overwritten data, or the bottomless well of cloud bill shock. To reduce the risks, OpenAI supports an extension x-openai-isConsequential that you can add to your OpenAPI description, to indicate which endpoints should not be called without a human confirmation step.

I’m not doing much with OpenAI right now, but I do plenty with OpenAPI and the question “how do I add this field to my existing API description?” is one that I can answer! What’s more, you can use the advice in this post to add other extensions or additions to your OpenAPI descriptions using Overlays, this advice isn’t OpenAI-specific, but it’s used in the examples. Continue reading →

20 Nov
2023

When to version bump your OpenAPI description

I’ve heard a variety of bad advice (and some untruths!) regarding how to version your OpenAPI description lately. Rather than dig into those, instead I’ll share my opinion on how I like to version API descriptions in my own projects. Every API project is different, but perhaps there’s something here that can help your project too. Continue reading →
08 Nov
2023

API docs previews with Redoc and Netlify

I talk to a lot of people about their API lifecycles and processes, and one thing that has value in almost every case is immediate documentation preview for all updates to an OpenAPI description. The time it takes to set it up (about ten minutes now I know what to do) is an investment that makes every future change easier to propose, review, and accept. Here’s my recipe for open source OpenAPI documentation using Redoc (disclaimer: I work for Redocly, who publish Redoc) with the files pushed to Netlify for hosting (but it’s HTML, so really any hosting will do and you should feel free to adapt the instructions for your preferred platform, and then share them in the comments). Continue reading →
20 Jun
2023

Visualise OpenAPI with Blockly

Giving talks about OpenAPI often means lots and lots of slides of YAML. In fact, one of my talks even contains a “warning, contains yaml” slide! If you aren’t a professional yaml developer, it can be difficult to digest and learn from, and so I wanted to do better. The various elements are nested inside one another, and so I had this idea to build a representation of OpenAPI using Blockly (the tooling also used for Scratch, if you’ve seen that).

Showing tags with descriptions
Continue reading →

12 Jun
2023

Tips for better documentation with OpenAPI

I love documentation, which is supposed to be rare for software engineers. I am pretty sure that loving documentation is actually very common, but not very cool and so few people admit to it! I love reading good docs, and so I love writing them too. Between hanging out in the Write the Docs community, and recently being at the APItheDocs conference, I’ve answered a bunch of questions about getting good documentation from an OpenAPI document, so I thought I’d round them up in case it’s useful. Continue reading →
16 Nov
2020

Making SDKs a Value-Added Experience

I’ve been working with SDKs quite a bit this year, simple ones that wrap a bunch of API endpoints. The best bits of these SDKs isn’t just the delightful developer experience of using the clunky endpoints with the elegant SDK wrapping them. I mean, it is, but I already wrote about consistent and Delightful SDKs for Nordic APIs; today I want to cover the some of the “extra” things that make a big difference in the APIs. Continue reading →