A base Images API for the API Commons — upload, metadata, renditions, and deletion, described once.
Images have been done. There is no good reason every application invents its own upload endpoint, its own metadata shape, and its own way of asking for a smaller version of the same picture.
- openapi.yml — OpenAPI 3.1 covering list, create, read, update, delete, and renditions.
- apis.yml — the APIs.json index for this base.
| Operation | Method | Path |
|---|---|---|
listImages |
GET | /images |
createImage |
POST | /images |
getImage |
GET | /images/{imageId} |
updateImage |
PATCH | /images/{imageId} |
deleteImage |
DELETE | /images/{imageId} |
getImageRendition |
GET | /images/{imageId}/renditions |
Three choices worth keeping when you copy it:
Upload is two steps. POST /images creates the record and returns a short-lived
upload.url to PUT the bytes to. That keeps large binaries off the JSON API, lets you
hand out a pre-signed storage URL, and means a failed upload does not lose the metadata.
The image sits in pending until the bytes arrive.
Renditions are requested, not enumerated. A client asks for the width and format it wants; it never has to discover which fixed variants happen to exist.
alt is on the base. An image API that makes the text alternative easy to skip
produces an inaccessible product downstream.
Every API Commons base errors the same way: RFC 9457
problem details, application/problem+json, with the same Problem schema and the same
set of named responses lifted from
problem-details-for-http-apis.
That block is byte-identical across the bases on purpose. If you adopt more than one, your clients parse one error format.
Conformance is checked by the Problem Details Spectral ruleset:
spectral lint openapi.yml \
-r https://raw.githubusercontent.com/api-commons/spectral-problem-details-ruleset/main/problem-details.yaml
This file lints clean under that ruleset, and under spectral:oas apart from one
deliberate warning: oas3-api-servers. A base template has no server, and adding a
placeholder would only trip oas3-server-not-example.com. Add your own servers when
you adopt it.
Copy openapi.yml into your own repo and change it. This is a starting point, not a
dependency — there is no hosted API behind it and nothing to install. Keep the error
components as they are and you inherit a standard error contract for free.
apis.yml is the APIs.json index for this base, pointing at the
OpenAPI, this repository, the ruleset, and the documentation.
The artifacts in this repository — the schemas, examples, and API descriptions — are licensed CC BY-NC-SA 4.0 (Attribution–NonCommercial–ShareAlike).
API Commons licenses artifacts under CC BY-NC-SA 4.0 and code under Apache-2.0.
A machine-readable building block from API Commons — open specifications and schemas for the APIs you produce and consume. See all building blocks at apicommons.org and the tools at apicommons.org/tools.
Related building blocks
- plans — access plans, tiers, and pricing
- rate-limits — the quotas an API enforces
- starters — the smallest correct version of each artifact