https://openapi-proxy.com

Spec versions

Every document you upload becomes a version, and a version is immutable. It is identified by the SHA-256 of its exact bytes, which has three consequences worth knowing before you automate anything.

Re-uploading the same document is not an error and not a new version. A CI job that posts openapi.json on every merge produces one version per actual change, not one per build. The console says "those bytes are already a version here"; the API answers 200 with the version that already existed rather than 201.

The digest means the bytes, not the meaning. Reformat the JSON, reorder two keys, add a trailing newline, and you get a different version - because we cannot know that your tooling did not also change something that matters. If you want stable digests, put the document through the same formatter every time.

What you upload is what you get back. Download on a version hands back those bytes exactly: same key order, same comments if it was YAML, same trailing newline. That is a promise rather than a nicety, since a round trip that reformatted the document would quietly invalidate every digest you had written down.

Getting a document in

Four ways, all of them the same door:

  • Paste it into the box.
  • Fetch it from a URL - a raw GitHub link, a /openapi.json on a staging box, a published portal. We fetch it once, now, and keep the bytes; the proxy does not go back to that address later, so nothing changes under you because something upstream was edited.
  • curl -T, which is the same as pasting from a terminal.
  • The CLI or API - see The API and the CLI.

Addresses on private networks are refused. We fetch from the public internet on your behalf and nowhere else, which is a rule about our network rather than a comment on yours.

Publishing

Uploading a version does not put it in front of traffic. The first version on a proxy publishes itself, because a proxy with a document nobody has published is a proxy that does nothing; every version after that waits for you.

Publishing swaps a pointer:

  • Requests already in flight finish against the version they started on.
  • New requests see the new one, on the fleet's next registry poll - seconds, not a deploy.
  • Rolling back is publishing the older version again. It is the same action in the other direction, which is the property that makes it usable at 3am.

Versions are never deleted, so the pointer can always go back.

Editing

The edit button on a version opens the upload box with those bytes already in it, because a new version is nearly always the current one with a change. Saving adds a version; it never overwrites the one you started from, and nothing is live until you publish it.

  • Environments - when one published version is not enough, because staging and production are running different contracts on purpose.
  • What changed when it shipped - the diff between two versions, in contract and in reality.