LornaJane

Welcome! I’m Lorna: open source technology leader and developer experience engineer. I’m a striking combination of technical experience, communication skills, and a genuine love for enabling others to succeed. I’m a leader, an engineer, a writer, a user champion, an open source maintainer, and a public speaker. My passion is taking great technology, and making it a great experience for users.

On this site you’ll find my blog, links to things I’ve done in other places, and my contact details. I’m always happy to hear from others in the industry and you are welcome to reach out to me with requests for articles, podcasts, or speaking – I can’t do everything, but that doesn’t stop me trying!

From The Blog

26 Mar

2025

Right-Size Your RESTful API: More Flexibility Without GraphQL

If 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. Continue reading →

Posted in tech | 2 Replies

12 Mar

2025

Markdown/Mermaid output for OpenAPI Arazzo

API 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 assets in a project. HTML-format API reference documentation does a great job of building that bridge when working on OpenAPI projects, but now I’m using Arazzo and it’s a very new standard with not nearly as many tools available for that format yet – so I built one. –

Posted in tech | 1 Reply

17 Feb

2025

From HTTP to OpenAPI with Optic

I’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. Continue reading →

Posted in tech | 1 Reply

Talks, Articles, Podcasts, and More

From The Blog

Right-Size Your RESTful API: More Flexibility Without GraphQL

Markdown/Mermaid output for OpenAPI Arazzo

From HTTP to OpenAPI with Optic

Talks, Articles, Podcasts, and More

OpenAPI for Web Developers

New OpenAPI Standards

Panel: Maintaining Open Source Software

OpenAPI Standards Landscape

Beyond the README

CLI Magic for Docs Projects