Permalink
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
188 lines (101 sloc) 7.6 KB
outputFileName
index.html

Creating and writing to a stream

You write to a stream over HTTP using a POST request to the resource of the stream. If the stream does not exist then the stream is implicitly created.

Event Store media types

Event Store supports a custom media type for posting events, application/vnd.eventstore.events+json or application/vnd.eventstore.events+xml. This format allows for extra functionality that posting events as application/json or application/xml does not. For example it allows you to post multiple events in a single batch.

The format represents data with the following jschema (eventId must be a UUID).

[
    {
      "eventId"    : "string",
      "eventType"  : "string",
      "data"       : "object",
      "metadata"   : "object"
    }
]

Writing a single event

If you issue a POST request with data to a stream and the correct content type set it writes the event to the stream, and generates a 201 response from the server, giving you the location of the event. Using the following event, which you can also download as a file:

[!code-jsonhttp-api-writing-single-event]

POST the following request to create a stream and add an event to it:

Request

[!code-bashhttp-api-write-event-request]

Response

[!code-jsonhttp-api-write-event-response]


Some clients may not be able to generate a unique identifier (or may not want to) for the event ID. You need this ID for idempotence purposes and Event Store can generate it for you.

If you leave off the ES-EventId header you see different behavior:

Request

[!code-bashhttp-api-write-event-no-id-request]

Response

[!code-jsonhttp-api-write-event-no-id-response]


In this case Event Store has responded with a 307 Temporary Redirect. The location points to another URI that you can post the event to. This new URI is idempotent for posting, even without an event ID.

Request

[!code-bashhttp-api-write-event-follow-request]

Response

[!code-jsonhttp-api-write-event-follow-response]


It's generally recommended to include an event ID if possible as it results in fewer round trips between the client and the server.

When posting to either the stream or to the returned redirect, clients must include the EventType header. If you forget to include the header you receive an error.

Request

[!code-bashhttp-api-write-event-no-type-request]

Response

[!code-jsonhttp-api-write-event-no-type-response]


Batch writes

You can include more than one write in a single post by placing multiple events inside of the array representing the events, including metadata.

For example, the below has two events:

[!code-jsonhttp-api-multiple-events]

When you write multiple events in a single post, Event Store treats them transactionally, it writes all events together or fails.

Request

[!code-bashhttp-api-write-multiple-events-request]

Response

[!code-jsonhttp-api-write-multiple-events-response]


Appending events

To append events, issue a POST request to the same resource again and edit the eventId:

[!code-jsonhttp-api-append-event]

Request

[!code-bashhttp-api-write-event-append-request]

Response

[!code-jsonhttp-api-write-event-append-response]


Data-only events

Version 3.7.0 of Event Store added support for the application/octet-stream content type to support data-only binary events. When creating these events, you need to provide the ES-EventType and ES-EventId headers and cannot have metadata associated with the event. In the example below SGVsbG8gV29ybGQ= is the data you POST to the stream:

Request

[!code-bashhttp-api-write-event-data-request]

Response

[!code-jsonhttp-api-write-event-data-response]


Expected version header

The expected version header represents the version of the stream you expect.

For example if you write to a stream at version 1, then you expect it to be at version 1 next time you write. This can allow for optimistic locking when multiple applications are reading/writing to streams.

If your expected version is not the current version you receive an HTTP status code of 400.

[!WARNING] See the idempotency section below, if you post the same event twice it is idempotent and won't return a version error.

First write an event to a stream, setting a version:

[!code-jsonhttp-api-append-event]

Download

Request

[!code-bashhttp-api-write-event-version-request]

Response

[!code-jsonhttp-api-write-event-version-response]


If you now write to the stream with the incorrect version, you receive an HTTP status code 400 error.

Request

[!code-bashhttp-api-write-event-wrong-version-request]

Response

[!code-jsonhttp-api-write-event-wrong-version-response]


There are special values you can use in the expected version header:

  • -2 states that this write should never conflict and should always succeed.
  • -1 states that the stream should not exist at the time of the writing (this write creates it).
  • 0 states that the stream should exist but should be empty.

Idempotency

Appends to streams are idempotent based upon the EventId assigned in your post. If you were to re-run the last command it returns the same value again.

This is important behaviour as it's how you implement error handling. If you receive a timeout, broken connection, no answer, etc from your HTTP POST then it's your responsibility to retry the post. You must also keep the same UUID that you assigned to the event in the first POST.

If you are using the expected version parameter with your post, then Event Store is 100% idempotent. If you use -2 as your expected version value, Event Store does its best to keep events idempotent but cannot assure that everything is fully idempotent and you end up in 'at-least-once' messaging. Read this guide for more details on idempotency.