Using OneOf for a property in an OpenAPI spec

When writing an OpenAPI specification, I came across the need for a particular property in an error response to be either a string or an object. This situation came about when validating a POST request that takes an items property that is a list of objects As a contrived example of a pet with accessories, consider this example request in curl: curl -X "POST" "http://api.example.com/pets" \ -H 'Content-Type: application/json' \ -d $'{ "name": "Rover", "items": [… continue reading.

Posted on 13 May 2025 in API, OpenAPI Leave a comment

Previewing OpenAPI specs using redocly's Docker container

To provide consistency between the environments of our developers, I'm a strong proponent of using containers so that every developer is using the same versions of our tools. This is really important for command line tooling that depends on a separately installed language such as NodeJS or PHP as a simple npm i -g can install wildly different versions if a dev is running an older (or newer!) version of Node. For OpenAPI specs, listing… continue reading.

Posted on 22 April 2025 in API, Docker, OpenAPI Leave a comment

RESTful APIs and media-types

Evert Pot recently posted REST is in the eye of the beholder. Go ahead and read it; it's good! It discusses the fact that most APIs that are self-described as RESTful are not hypermedia driven and hence are not actually RESTful as originally defined by Roy Fielding. Evert goes on to state that therefore the term "REST API" has changed to mean an HTTP API that isn't hypermedia-driven. I think that what the world currently… continue reading.

Posted on 25 August 2016 in API

API errors are first class citizens

It seems to me that error handling is an afterthought in far too many APIs. When designing an API, I implore you to design your error handling too! The way that your API presents an error is key to a good API; developers integrating with your API will judge you on it. Follow the HTTP rules Just because it's an error doesn't mean that you can forget your HTTP. You need to be a great… continue reading.

Posted on 13 July 2016 in API

Category: API