Migrating to the v2 API

Both APIs run side by side in 1.3, on the same port and the same data, with the same API token. You can therefore move one route at a time: what one client writes through v2, another reads through v1, and the other way round. Every response of the v1 API carries a Deprecation header and a Sunset header, so a proxy or a log shows which clients still use it.

If you use an official client SDK, update it to its version for EventSourcingDB 1.3, which speaks v2 by itself.

What Stays the Same#

The events do not change: a client writes and reads the same CloudEvents, with the same subjects, event types, and sources. Preconditions, EventQL, the options of reading and observing, such as bounds and fromLatestEvent, and the API token work as before.

What Changes Everywhere#

• Routes live below /api/v2/<category>/<route>, in the categories data, management, and system, and some of them have new names, as the table below shows.
• Reads use QUERY rather than POST, since they change nothing. A proxy, load balancer, or firewall in front of EventSourcingDB has to let QUERY through.
• Every item of a response is an envelope whose content is in data, where v1 named it payload. A single answer, such as the one to reading an event type or to the diagnosis, is an envelope as well, where v1 sent it bare.
• Every finite stream ends with an end item, and a stream that breaks off without it was cut. Every stream sends heartbeat items while it has nothing else to send, including writing events and registering a schema, whose answers are streams now.
• Errors are reported in the response, with status 200 and an item of the type error that names its code, rather than through status codes such as 409 or 404. See Errors.
• As in v1, a body has to have exactly the shape a route expects: a field the route does not know, or null where it takes none, is rejected with 400, and the response names where it lies. A missing field or a wrong value, which v1 refused with 400 as well, is reported as an error item with status 200.
• A request to a route that takes a body has to name its content type in the Content-Type header, application/json, or application/x-ndjson for restoring a backup or importing events, which parameters such as charset=utf-8 may follow. A request without it, or with another one, is rejected with 400; v1 does not check it.
• Answers that the server makes up itself, such as the one to ping, are CloudEvents in an envelope of the type event.

Routes#

Importing and exporting events, as described in Export and Import, and incremental backups exist only in the v2 API; the v1 API has no counterpart for them.

What Changes per Route#

• Writing events answers with a stream of the written events, as items of the type event, followed by end, rather than with a JSON array. The preconditions on a subject take an option recursive, which applies them to everything below the subject as well, see Checking a Subject and Everything Below It.
• Listing subjects takes the subject as subject, where v1 named it baseSubject, and lists it alone unless options.recursive is true. v1 always listed every subject below it as well, so set recursive to true to get what v1 returned.
• Listing event types and reading an event type name the type type, where v1 named it eventType, and say whether it has events as hasEvents, which is the opposite of v1's isPhantom. Reading an event type that the database does not know is reported as event-type-unknown rather than with 404.
• Registering an event schema names the type type, where v1 named it eventType, both in the request and in the event-schema-registered event it answers with, which now comes in a stream.
• Running an EventQL query sends each result as an item of the type row, as v1 did, but holds the result in data.value rather than in payload itself. A mistake in the query names its position, where it is known, in its details, as start and end, each with a line and a column.
• Creating a backup takes lastBackedUpEvent: null for a full backup, or the id and hash of the event a previous backup ended at for an increment that holds only what was written since. It answers in a format of its own, with a backup item, the eventSchema and event items, the lastBackedUpEvent it ended at, and end, where v1 sent schema and event lines with nothing that marks the beginning or the end of the backup, see create-backup. Restoring a backup takes a full backup followed by its increments, and also a backup that v1 wrote. Like the v1 API of this version, it refuses a schema in such a backup that does not describe an object, which earlier versions accepted. See Backup and Restore.
• Auditing the event store takes lastAuditedEvent, the id and hash of the event a previous audit ended at, or null for a first audit, where v1 took latestEventId and latestEventHash. See Auditing the Event Store.
• Verifying the store sends what it finds as items of the type finding.
• Enabling read-only mode answers with a read-only-mode-enabled event, and reports read-only-mode-already-enabled if the mode is on already.
• Ping answers with a ping-received event, and verifying the token with a token-verified event, where v1 named it api-token-verified.
• Health chooses OpenMetrics through the Accept header, as application/openmetrics-text, rather than through ?format=openmetrics, and answers a status of fail with 503 rather than 500. Its metrics have new names, so queries and alerts that use those of v1 need rewriting. See Logging and Monitoring.
• The diagnosis is a POST to diagnose and answers with a server-diagnosed event, which also holds the options that v1 leaves out. It gives the remaining time of the license and the heartbeat interval in seconds rather than nanoseconds, as remainingDurationInSeconds and heartbeatIntervalInSeconds, where v1 named them remainingDuration and heartbeatInterval, see Diagnostics and Troubleshooting.
• The OpenAPI definition of v2 is JSON, where that of v1 is YAML. The API catalog at /.well-known/api-catalog lists both.

Errors#

Where v1 answered with a status code, v2 answers with status 200 and an error item that names its code. A route that answers with a stream sends the error as an item of that stream. This section compares v2 with the v1 API of 1.3, which answers some cases differently than 1.2 did. The most common cases:

Some status codes stay, since they report a problem of the request or the server rather than of what it asks for: 400 for a body of the wrong shape, 401, 404 for a route that does not exist, 405, 408, 413, 429, 500, and 503 for a server that shuts down before it has answered. The overview of the errors lists every code.