HTTP Overview

#HTTP API - Overview

The Event Store provides an AtomPub over HTTP as a native interface. This section of the documentation will document the options for reading and manipulating streams using the API.

Examples in this section make use of the command line tool to construct HTTP requests.

##Rationale

The reason the AtomPub API exists is that it provides a straightforward way to interact with the Event Store to any environment capable of making HTTP requests. It also gives the advantage that it becomes easy to use the Event Store in heterogenous environments, with components in several different runtimes (for example, you can imagine having SmallTalk, C# and Haskell access streams of events in order to allow use cases to be implemented in a style best suited to them). It also opens up the possibility of using the Event Store as a queuing system.

AtomPub is a RESTful protocol. Consequently, it can reuse many existing components, for example Reverse Proxies and client's native HTTP caching. Since events stored in the Event Store are entirely immutable, cache expirations can be infinite. We can also leverage content type negotiation - appropriately serialized events can be accessed as JSON or XML according to the request headers.

##Factors affecting choice of API

Although there are a number of advantages to using the AtomPub API, there are also some disadvantages.

If you discount intermediate caching, the protocol is more expensive than the TCP protocol. On a reasonably specified machine, the Event Store can service between 1 and 2 thousand requests per second as AtomPub over HTTP - an order of magnitude lower than can be serviced over TCP.

There is also a latency increase when using AtomPub, as a component wishing to subscribe would poll for new events rather than having new events pushed to it as can be the case with the TCP API.

##Compatibility with AtomPub

Although the Event Store is intended to be compatible with the AtomPub protocol, there are a number of places where extensions have been made to the protocol.

NOTE: Although the Event Store currently returns a media type of application/atom+x.json, this will change in a subsequent release to be a vendor specific media type.

It is not recommended to rely on any behaviour which is in conflict with the AtomPub protocol unless it is explictly listed here, as such behaviour is likely to be fixed in subsequent releases of the Event Store.

###Content Types

The preferred way of determining with which content type responses will be served is to set the Accept header on the request. However, as some clients do not deal well with HTTP headers when caching, appending a format parameter to the URL is also supported.

The accepted content types for POST requests are currently:

• application/xml
• application/json
• text/xml

In addition to those, these content types are also accepted for GET requests:

• application/atom+xml
• application/atom+x.json (As noted above, this will change to be a vendor specific media type)

These types can be specified in the URL by appending a query string:

• format=xml
• format=json

It is important to note that if the content type is set to be XML, posting JSON will fail, and vice-versa.

###Batching

It is possible to post multiple items into a stream using a single request. Events posted in the same request are treated transactionally.