# Reading streams and events

# Reading a stream

EventStoreDB exposes streams as a resource located at http(s)://{yourdomain.com}:{port}/streams/{stream}. If you issue a simple GET request to this resource, you receive a standard AtomFeed document as a response.

curl -i -H "Accept:application/vnd.eventstore.atom+json" "http://127.0.0.1:2113/streams/newstream" -u "admin:changeit"

HTTP/1.1 200 OK
Access-Control-Allow-Methods: POST, DELETE, GET, OPTIONS
Access-Control-Allow-Headers: Content-Type, X-Requested-With, X-Forwarded-Host, X-Forwarded-Prefix, X-PINGOTHER, Authorization, ES-LongPoll, ES-ExpectedVersion, ES-EventId, ES-EventType, ES-RequiresMaster, ES-HardDelete, ES-ResolveLinkTos
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: Location, ES-Position, ES-CurrentVersion
Cache-Control: max-age=0, no-cache, must-revalidate
Vary: Accept
ETag: "0;-2060438500"
Content-Type: application/vnd.eventstore.atom+json; charset=utf-8
Server: Mono-HTTPAPI/1.0
Date: Fri, 15 Dec 2017 12:23:23 GMT
Content-Length: 1262
Keep-Alive: timeout=15,max=100

{
  "title": "Event stream 'newstream'",
  "id": "http://127.0.0.1:2113/streams/newstream",
  "updated": "2017-12-15T12:19:32.021776Z",
  "streamId": "newstream",
  "author": {
    "name": "EventStore"
  },
  "headOfStream": true,
  "selfUrl": "http://127.0.0.1:2113/streams/newstream",
  "eTag": "0;-2060438500",
  "links": [
    {
      "uri": "http://127.0.0.1:2113/streams/newstream",
      "relation": "self"
    },
    {
      "uri": "http://127.0.0.1:2113/streams/newstream/head/backward/20",
      "relation": "first"
    },
    {
      "uri": "http://127.0.0.1:2113/streams/newstream/1/forward/20",
      "relation": "previous"
    },
    {
      "uri": "http://127.0.0.1:2113/streams/newstream/metadata",
      "relation": "metadata"
    }
  ],
  "entries": [
    {
      "title": "0@newstream",
      "id": "http://127.0.0.1:2113/streams/newstream/0",
      "updated": "2017-12-15T12:19:32.021776Z",
      "author": {
        "name": "EventStore"
      },
      "summary": "event-type",
      "links": [
        {
          "uri": "http://127.0.0.1:2113/streams/newstream/0",
          "relation": "edit"
        },
        {
          "uri": "http://127.0.0.1:2113/streams/newstream/0",
          "relation": "alternate"
        }
      ]
    }
  ]
}

// Make sure to add code blocks to your code group

# Reading an event from a stream

The feed has one item in it, and if there are more than one, then items are sorted from newest to oldest.

For each entry, there are a series of links to the actual events, we cover embedding data into a stream later. To GET an event, follow the alternate link and set your Accept headers to the mime type you would like the event in.

The accepted content types for GET requests are:

application/xml
application/atom+xml
application/json
application/vnd.eventstore.atom+json
text/xml
text/html

The non-atom version of the event has fewer details about the event.

curl -i http://127.0.0.1:2113/streams/newstream/0 -H "Accept: application/json" -u "admin:changeit"

curl -i http://127.0.0.1:2113/streams/newstream/0 -H "Accept: application/json" -u "admin:changeit"

// Make sure to add code blocks to your code group

# Feed paging

The next step in understanding how to read a stream is the first/last/previous/next links within a stream. EventStoreDB supplies these links so you can read through a stream, and they follow the pattern defined in RFC 5005 (opens new window).

In the example above the server returned the following links as part of its result:

#region curl
curl -i -H "Accept:application/vnd.eventstore.atom+json" "http://127.0.0.1:2113/streams/newstream" -u "admin:changeit"
#endregion curl

#region response
HTTP/1.1 200 OK
Access-Control-Allow-Methods: POST, DELETE, GET, OPTIONS
Access-Control-Allow-Headers: Content-Type, X-Requested-With, X-Forwarded-Host, X-Forwarded-Prefix, X-PINGOTHER, Authorization, ES-LongPoll, ES-ExpectedVersion, ES-EventId, ES-EventType, ES-RequiresMaster, ES-HardDelete, ES-ResolveLinkTos
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: Location, ES-Position, ES-CurrentVersion
Cache-Control: max-age=0, no-cache, must-revalidate
Vary: Accept
ETag: "0;-2060438500"
Content-Type: application/vnd.eventstore.atom+json; charset=utf-8
Server: Mono-HTTPAPI/1.0
Date: Fri, 15 Dec 2017 12:23:23 GMT
Content-Length: 1262
Keep-Alive: timeout=15,max=100

{
  "title": "Event stream 'newstream'",
  "id": "http://127.0.0.1:2113/streams/newstream",
  "updated": "2017-12-15T12:19:32.021776Z",
  "streamId": "newstream",
  "author": {
    "name": "EventStore"
  },
  "headOfStream": true,
  "selfUrl": "http://127.0.0.1:2113/streams/newstream",
  "eTag": "0;-2060438500",
  "links": [
    {
      "uri": "http://127.0.0.1:2113/streams/newstream",
      "relation": "self"
    },
    {
      "uri": "http://127.0.0.1:2113/streams/newstream/head/backward/20",
      "relation": "first"
    },
    {
      "uri": "http://127.0.0.1:2113/streams/newstream/1/forward/20",
      "relation": "previous"
    },
    {
      "uri": "http://127.0.0.1:2113/streams/newstream/metadata",
      "relation": "metadata"
    }
  ],
  "entries": [
    {
      "title": "0@newstream",
      "id": "http://127.0.0.1:2113/streams/newstream/0",
      "updated": "2017-12-15T12:19:32.021776Z",
      "author": {
        "name": "EventStore"
      },
      "summary": "event-type",
      "links": [
        {
          "uri": "http://127.0.0.1:2113/streams/newstream/0",
          "relation": "edit"
        },
        {
          "uri": "http://127.0.0.1:2113/streams/newstream/0",
          "relation": "alternate"
        }
      ]
    }
  ]
}
#endregion response

This shows that there is not a next URL as all the information is in this request and that the URL requested is the first link. When dealing with these URLs, there are two ways of reading the data in the stream.

You GET the last link and move backwards following previous links, or
You GET the first link and follow the next links, and the final item will not have a next link.

If you want to follow a live stream, then you keep following the previous links. When you reach the end of a stream, you receive an empty document with no entries or previous link. You then continue polling this URI (in the future a document will appear). You can see this by trying the previous link from the above feed.

curl -i http://127.0.0.1:2113/streams/newstream/1/forward/20 -H "Accept:application/vnd.eventstore.atom+json"

HTTP/1.1 200 OK
Access-Control-Allow-Methods: GET, OPTIONS
Access-Control-Allow-Headers: Content-Type, X-Requested-With, X-PINGOTHER, Authorization, ES-LongPoll, ES-ExpectedVersion, ES-EventId, ES-EventType, ES-RequiresMaster, ES-HardDelete, ES-ResolveLinkTo, ES-ExpectedVersion
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: Location, ES-Position
Cache-Control: max-age=0, no-cache, must-revalidate
Vary: Accept
ETag: "0;248368668"
Content-Type: application/vnd.eventstore.atom+json; charset=utf-8
Server: Mono-HTTPAPI/1.0
Date: Fri, 13 Mar 2015 14:04:47 GMT
Content-Length: 795
Keep-Alive: timeout=15,max=100

{
  "title": "Event stream 'newstream'",
  "id": "<http://127.0.0.1:2113/streams/newstream">,
  "updated": "0001-01-01T00:00:00Z",
  "streamId": "newstream",
  "author": {
    "name": "EventStore"
  },
  "headOfStream": false,
  "links": [
    {
      "uri": "http://127.0.0.1:2113/streams/newstream",
      "relation": "self"
    },
    {
      "uri": "http://127.0.0.1:2113/streams/newstream/head/backward/20",
      "relation": "first"
    },
    {
      "uri": "http://127.0.0.1:2113/streams/newstream/0/forward/20",
      "relation": "last"
    },
    {
      "uri": "http://127.0.0.1:2113/streams/newstream/0/backward/20",
      "relation": "next"
    },
    {
      "uri": "http://127.0.0.1:2113/streams/newstream/metadata",
      "relation": "metadata"
    }
  ],
  "entries": \[]
}

// Make sure to add code blocks to your code group

When parsing an atom subscription, the IDs of events always stay the same. This is important for figuring out if you are referring to the same event.

# Paging through events

Let's now try an example with more than a single page. First create the multiple events:

curl -i -d "@paging-events.json" "http://127.0.0.1:2113/streams/alphabet" -H "Content-Type:application/vnd.eventstore.events+json"

HTTP/1.1 100 Continue

HTTP/1.1 201 Created
Access-Control-Allow-Methods: POST, DELETE, GET, OPTIONS
Access-Control-Allow-Headers: Content-Type, X-Requested-With, X-Forwarded-Host, X-Forwarded-Prefix, X-PINGOTHER, Authorization, ES-LongPoll, ES-ExpectedVersion, ES-EventId, ES-EventType, ES-RequiresMaster, ES-HardDelete, ES-ResolveLinkTos
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: Location, ES-Position, ES-CurrentVersion
Location: http://127.0.0.1:2113/streams/alphabet/0
Content-Type: text/plain; charset=utf-8
Server: Mono-HTTPAPI/1.0
Date: Tue, 21 Aug 2018 09:53:46 GMT
Content-Length: 0
Keep-Alive: timeout=15,max=100

// Make sure to add code blocks to your code group

If you request the stream of events, you see a series of links above the events:

curl -i http://127.0.0.1:2113/streams/alphabet \
    -H "Accept:application/vnd.eventstore.atom+json"

HTTP/1.1 200 OK
Access-Control-Allow-Methods: POST, DELETE, GET, OPTIONS
Access-Control-Allow-Headers: Content-Type, X-Requested-With, X-Forwarded-Host, X-Forwarded-Prefix, X-PINGOTHER, Authorization, ES-LongPoll, ES-ExpectedVersion, ES-EventId, ES-EventType, ES-RequiresMaster, ES-HardDelete, ES-ResolveLinkTos
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: Location, ES-Position, ES-CurrentVersion
Cache-Control: max-age=0, no-cache, must-revalidate
Vary: Accept
ETag: "26;-2060438500"
Content-Type: application/vnd.eventstore.atom+json; charset=utf-8
Server: Mono-HTTPAPI/1.0
Date: Tue, 21 Aug 2018 10:12:31 GMT
Content-Length: 10727
Keep-Alive: timeout=15,max=100

{
  "title": "Event stream 'alphabet'",
  "id": "http://127.0.0.1:2113/streams/alphabet",
  "updated": "2018-08-21T09:53:46.869815Z",
  "streamId": "alphabet",
  "author": {
    "name": "EventStore"
  },
  "headOfStream": true,
  "selfUrl": "http://127.0.0.1:2113/streams/alphabet",
  "eTag": "26;-2060438500",
  "links": [
    {
      "uri": "http://127.0.0.1:2113/streams/alphabet",
      "relation": "self"
    },
    {
      "uri": "http://127.0.0.1:2113/streams/alphabet/head/backward/20",
      "relation": "first"
    },
    {
      "uri": "http://127.0.0.1:2113/streams/alphabet/0/forward/20",
      "relation": "last"
    },
    {
      "uri": "http://127.0.0.1:2113/streams/alphabet/6/backward/20",
      "relation": "next"
    },
    {
      "uri": "http://127.0.0.1:2113/streams/alphabet/27/forward/20",
      "relation": "previous"
    },
    {
      "uri": "http://127.0.0.1:2113/streams/alphabet/metadata",
      "relation": "metadata"
    }
  ],
  "entries": [
    {
      "title": "26@alphabet",
      "id": "http://127.0.0.1:2113/streams/alphabet/26",
      "updated": "2018-08-21T09:53:46.869815Z",
      "author": {
        "name": "EventStore"
      },
      "summary": "event-type",
      "links": [
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/26",
          "relation": "edit"
        },
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/26",
          "relation": "alternate"
        }
      ]
    },
    {
      "title": "25@alphabet",
      "id": "http://127.0.0.1:2113/streams/alphabet/25",
      "updated": "2018-08-21T09:53:46.869811Z",
      "author": {
        "name": "EventStore"
      },
      "summary": "event-type",
      "links": [
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/25",
          "relation": "edit"
        },
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/25",
          "relation": "alternate"
        }
      ]
    },
    {
      "title": "24@alphabet",
      "id": "http://127.0.0.1:2113/streams/alphabet/24",
      "updated": "2018-08-21T09:53:46.869809Z",
      "author": {
        "name": "EventStore"
      },
      "summary": "event-type",
      "links": [
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/24",
          "relation": "edit"
        },
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/24",
          "relation": "alternate"
        }
      ]
    },
    {
      "title": "23@alphabet",
      "id": "http://127.0.0.1:2113/streams/alphabet/23",
      "updated": "2018-08-21T09:53:46.869806Z",
      "author": {
        "name": "EventStore"
      },
      "summary": "event-type",
      "links": [
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/23",
          "relation": "edit"
        },
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/23",
          "relation": "alternate"
        }
      ]
    },
    {
      "title": "22@alphabet",
      "id": "http://127.0.0.1:2113/streams/alphabet/22",
      "updated": "2018-08-21T09:53:46.869804Z",
      "author": {
        "name": "EventStore"
      },
      "summary": "event-type",
      "links": [
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/22",
          "relation": "edit"
        },
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/22",
          "relation": "alternate"
        }
      ]
    },
    {
      "title": "21@alphabet",
      "id": "http://127.0.0.1:2113/streams/alphabet/21",
      "updated": "2018-08-21T09:53:46.869802Z",
      "author": {
        "name": "EventStore"
      },
      "summary": "event-type",
      "links": [
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/21",
          "relation": "edit"
        },
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/21",
          "relation": "alternate"
        }
      ]
    },
    {
      "title": "20@alphabet",
      "id": "http://127.0.0.1:2113/streams/alphabet/20",
      "updated": "2018-08-21T09:53:46.869799Z",
      "author": {
        "name": "EventStore"
      },
      "summary": "event-type",
      "links": [
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/20",
          "relation": "edit"
        },
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/20",
          "relation": "alternate"
        }
      ]
    },
    {
      "title": "19@alphabet",
      "id": "http://127.0.0.1:2113/streams/alphabet/19",
      "updated": "2018-08-21T09:53:46.869791Z",
      "author": {
        "name": "EventStore"
      },
      "summary": "event-type",
      "links": [
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/19",
          "relation": "edit"
        },
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/19",
          "relation": "alternate"
        }
      ]
    },
    {
      "title": "18@alphabet",
      "id": "http://127.0.0.1:2113/streams/alphabet/18",
      "updated": "2018-08-21T09:53:46.869788Z",
      "author": {
        "name": "EventStore"
      },
      "summary": "event-type",
      "links": [
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/18",
          "relation": "edit"
        },
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/18",
          "relation": "alternate"
        }
      ]
    },
    {
      "title": "17@alphabet",
      "id": "http://127.0.0.1:2113/streams/alphabet/17",
      "updated": "2018-08-21T09:53:46.869786Z",
      "author": {
        "name": "EventStore"
      },
      "summary": "event-type",
      "links": [
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/17",
          "relation": "edit"
        },
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/17",
          "relation": "alternate"
        }
      ]
    },
    {
      "title": "16@alphabet",
      "id": "http://127.0.0.1:2113/streams/alphabet/16",
      "updated": "2018-08-21T09:53:46.869782Z",
      "author": {
        "name": "EventStore"
      },
      "summary": "event-type",
      "links": [
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/16",
          "relation": "edit"
        },
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/16",
          "relation": "alternate"
        }
      ]
    },
    {
      "title": "15@alphabet",
      "id": "http://127.0.0.1:2113/streams/alphabet/15",
      "updated": "2018-08-21T09:53:46.86978Z",
      "author": {
        "name": "EventStore"
      },
      "summary": "event-type",
      "links": [
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/15",
          "relation": "edit"
        },
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/15",
          "relation": "alternate"
        }
      ]
    },
    {
      "title": "14@alphabet",
      "id": "http://127.0.0.1:2113/streams/alphabet/14",
      "updated": "2018-08-21T09:53:46.869778Z",
      "author": {
        "name": "EventStore"
      },
      "summary": "event-type",
      "links": [
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/14",
          "relation": "edit"
        },
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/14",
          "relation": "alternate"
        }
      ]
    },
    {
      "title": "13@alphabet",
      "id": "http://127.0.0.1:2113/streams/alphabet/13",
      "updated": "2018-08-21T09:53:46.869773Z",
      "author": {
        "name": "EventStore"
      },
      "summary": "event-type",
      "links": [
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/13",
          "relation": "edit"
        },
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/13",
          "relation": "alternate"
        }
      ]
    },
    {
      "title": "12@alphabet",
      "id": "http://127.0.0.1:2113/streams/alphabet/12",
      "updated": "2018-08-21T09:53:46.869771Z",
      "author": {
        "name": "EventStore"
      },
      "summary": "event-type",
      "links": [
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/12",
          "relation": "edit"
        },
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/12",
          "relation": "alternate"
        }
      ]
    },
    {
      "title": "11@alphabet",
      "id": "http://127.0.0.1:2113/streams/alphabet/11",
      "updated": "2018-08-21T09:53:46.869769Z",
      "author": {
        "name": "EventStore"
      },
      "summary": "event-type",
      "links": [
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/11",
          "relation": "edit"
        },
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/11",
          "relation": "alternate"
        }
      ]
    },
    {
      "title": "10@alphabet",
      "id": "http://127.0.0.1:2113/streams/alphabet/10",
      "updated": "2018-08-21T09:53:46.869766Z",
      "author": {
        "name": "EventStore"
      },
      "summary": "event-type",
      "links": [
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/10",
          "relation": "edit"
        },
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/10",
          "relation": "alternate"
        }
      ]
    },
    {
      "title": "9@alphabet",
      "id": "http://127.0.0.1:2113/streams/alphabet/9",
      "updated": "2018-08-21T09:53:46.869764Z",
      "author": {
        "name": "EventStore"
      },
      "summary": "event-type",
      "links": [
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/9",
          "relation": "edit"
        },
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/9",
          "relation": "alternate"
        }
      ]
    },
    {
      "title": "8@alphabet",
      "id": "http://127.0.0.1:2113/streams/alphabet/8",
      "updated": "2018-08-21T09:53:46.86976Z",
      "author": {
        "name": "EventStore"
      },
      "summary": "event-type",
      "links": [
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/8",
          "relation": "edit"
        },
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/8",
          "relation": "alternate"
        }
      ]
    },
    {
      "title": "7@alphabet",
      "id": "http://127.0.0.1:2113/streams/alphabet/7",
      "updated": "2018-08-21T09:53:46.869758Z",
      "author": {
        "name": "EventStore"
      },
      "summary": "event-type",
      "links": [
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/7",
          "relation": "edit"
        },
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/7",
          "relation": "alternate"
        }
      ]
    }
  ]
}

// Make sure to add code blocks to your code group

Using the links in the stream of events, you can traverse through all the events in the stream by going to the last URL and following previous links, or by following next links from the first link.

For example, if you request the last link from above:

curl -i http://127.0.0.1:2113/streams/alphabet/0/forward/20 \
    -H "Accept:application/vnd.eventstore.atom+json"

HTTP/1.1 200 OK
Access-Control-Allow-Methods: GET, OPTIONS
Access-Control-Allow-Headers: Content-Type, X-Requested-With, X-Forwarded-Host, X-Forwarded-Prefix, X-PINGOTHER, Authorization, ES-LongPoll, ES-ExpectedVersion, ES-EventId, ES-EventType, ES-RequiresMaster, ES-HardDelete, ES-ResolveLinkTos
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: Location, ES-Position, ES-CurrentVersion
Cache-Control: max-age=31536000, public
Vary: Accept
Content-Type: application/vnd.eventstore.atom+json; charset=utf-8
Server: Mono-HTTPAPI/1.0
Date: Tue, 21 Aug 2018 10:24:28 GMT
Content-Length: 10403
Keep-Alive: timeout=15,max=100

{
  "title": "Event stream 'alphabet'",
  "id": "http://127.0.0.1:2113/streams/alphabet",
  "updated": "2018-08-21T09:53:46.869716Z",
  "streamId": "alphabet",
  "author": {
    "name": "EventStore"
  },
  "headOfStream": false,
  "links": [
    {
      "uri": "http://127.0.0.1:2113/streams/alphabet",
      "relation": "self"
    },
    {
      "uri": "http://127.0.0.1:2113/streams/alphabet/head/backward/20",
      "relation": "first"
    },
    {
      "uri": "http://127.0.0.1:2113/streams/alphabet/20/forward/20",
      "relation": "previous"
    },
    {
      "uri": "http://127.0.0.1:2113/streams/alphabet/metadata",
      "relation": "metadata"
    }
  ],
  "entries": [
    {
      "title": "19@alphabet",
      "id": "http://127.0.0.1:2113/streams/alphabet/19",
      "updated": "2018-08-21T09:53:46.869791Z",
      "author": {
        "name": "EventStore"
      },
      "summary": "event-type",
      "links": [
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/19",
          "relation": "edit"
        },
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/19",
          "relation": "alternate"
        }
      ]
    },
    {
      "title": "18@alphabet",
      "id": "http://127.0.0.1:2113/streams/alphabet/18",
      "updated": "2018-08-21T09:53:46.869788Z",
      "author": {
        "name": "EventStore"
      },
      "summary": "event-type",
      "links": [
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/18",
          "relation": "edit"
        },
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/18",
          "relation": "alternate"
        }
      ]
    },
    {
      "title": "17@alphabet",
      "id": "http://127.0.0.1:2113/streams/alphabet/17",
      "updated": "2018-08-21T09:53:46.869786Z",
      "author": {
        "name": "EventStore"
      },
      "summary": "event-type",
      "links": [
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/17",
          "relation": "edit"
        },
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/17",
          "relation": "alternate"
        }
      ]
    },
    {
      "title": "16@alphabet",
      "id": "http://127.0.0.1:2113/streams/alphabet/16",
      "updated": "2018-08-21T09:53:46.869782Z",
      "author": {
        "name": "EventStore"
      },
      "summary": "event-type",
      "links": [
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/16",
          "relation": "edit"
        },
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/16",
          "relation": "alternate"
        }
      ]
    },
    {
      "title": "15@alphabet",
      "id": "http://127.0.0.1:2113/streams/alphabet/15",
      "updated": "2018-08-21T09:53:46.86978Z",
      "author": {
        "name": "EventStore"
      },
      "summary": "event-type",
      "links": [
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/15",
          "relation": "edit"
        },
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/15",
          "relation": "alternate"
        }
      ]
    },
    {
      "title": "14@alphabet",
      "id": "http://127.0.0.1:2113/streams/alphabet/14",
      "updated": "2018-08-21T09:53:46.869778Z",
      "author": {
        "name": "EventStore"
      },
      "summary": "event-type",
      "links": [
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/14",
          "relation": "edit"
        },
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/14",
          "relation": "alternate"
        }
      ]
    },
    {
      "title": "13@alphabet",
      "id": "http://127.0.0.1:2113/streams/alphabet/13",
      "updated": "2018-08-21T09:53:46.869773Z",
      "author": {
        "name": "EventStore"
      },
      "summary": "event-type",
      "links": [
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/13",
          "relation": "edit"
        },
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/13",
          "relation": "alternate"
        }
      ]
    },
    {
      "title": "12@alphabet",
      "id": "http://127.0.0.1:2113/streams/alphabet/12",
      "updated": "2018-08-21T09:53:46.869771Z",
      "author": {
        "name": "EventStore"
      },
      "summary": "event-type",
      "links": [
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/12",
          "relation": "edit"
        },
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/12",
          "relation": "alternate"
        }
      ]
    },
    {
      "title": "11@alphabet",
      "id": "http://127.0.0.1:2113/streams/alphabet/11",
      "updated": "2018-08-21T09:53:46.869769Z",
      "author": {
        "name": "EventStore"
      },
      "summary": "event-type",
      "links": [
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/11",
          "relation": "edit"
        },
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/11",
          "relation": "alternate"
        }
      ]
    },
    {
      "title": "10@alphabet",
      "id": "http://127.0.0.1:2113/streams/alphabet/10",
      "updated": "2018-08-21T09:53:46.869766Z",
      "author": {
        "name": "EventStore"
      },
      "summary": "event-type",
      "links": [
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/10",
          "relation": "edit"
        },
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/10",
          "relation": "alternate"
        }
      ]
    },
    {
      "title": "9@alphabet",
      "id": "http://127.0.0.1:2113/streams/alphabet/9",
      "updated": "2018-08-21T09:53:46.869764Z",
      "author": {
        "name": "EventStore"
      },
      "summary": "event-type",
      "links": [
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/9",
          "relation": "edit"
        },
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/9",
          "relation": "alternate"
        }
      ]
    },
    {
      "title": "8@alphabet",
      "id": "http://127.0.0.1:2113/streams/alphabet/8",
      "updated": "2018-08-21T09:53:46.86976Z",
      "author": {
        "name": "EventStore"
      },
      "summary": "event-type",
      "links": [
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/8",
          "relation": "edit"
        },
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/8",
          "relation": "alternate"
        }
      ]
    },
    {
      "title": "7@alphabet",
      "id": "http://127.0.0.1:2113/streams/alphabet/7",
      "updated": "2018-08-21T09:53:46.869758Z",
      "author": {
        "name": "EventStore"
      },
      "summary": "event-type",
      "links": [
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/7",
          "relation": "edit"
        },
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/7",
          "relation": "alternate"
        }
      ]
    },
    {
      "title": "6@alphabet",
      "id": "http://127.0.0.1:2113/streams/alphabet/6",
      "updated": "2018-08-21T09:53:46.869755Z",
      "author": {
        "name": "EventStore"
      },
      "summary": "event-type",
      "links": [
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/6",
          "relation": "edit"
        },
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/6",
          "relation": "alternate"
        }
      ]
    },
    {
      "title": "5@alphabet",
      "id": "http://127.0.0.1:2113/streams/alphabet/5",
      "updated": "2018-08-21T09:53:46.869753Z",
      "author": {
        "name": "EventStore"
      },
      "summary": "event-type",
      "links": [
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/5",
          "relation": "edit"
        },
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/5",
          "relation": "alternate"
        }
      ]
    },
    {
      "title": "4@alphabet",
      "id": "http://127.0.0.1:2113/streams/alphabet/4",
      "updated": "2018-08-21T09:53:46.86975Z",
      "author": {
        "name": "EventStore"
      },
      "summary": "event-type",
      "links": [
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/4",
          "relation": "edit"
        },
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/4",
          "relation": "alternate"
        }
      ]
    },
    {
      "title": "3@alphabet",
      "id": "http://127.0.0.1:2113/streams/alphabet/3",
      "updated": "2018-08-21T09:53:46.869748Z",
      "author": {
        "name": "EventStore"
      },
      "summary": "event-type",
      "links": [
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/3",
          "relation": "edit"
        },
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/3",
          "relation": "alternate"
        }
      ]
    },
    {
      "title": "2@alphabet",
      "id": "http://127.0.0.1:2113/streams/alphabet/2",
      "updated": "2018-08-21T09:53:46.869746Z",
      "author": {
        "name": "EventStore"
      },
      "summary": "event-type",
      "links": [
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/2",
          "relation": "edit"
        },
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/2",
          "relation": "alternate"
        }
      ]
    },
    {
      "title": "1@alphabet",
      "id": "http://127.0.0.1:2113/streams/alphabet/1",
      "updated": "2018-08-21T09:53:46.869742Z",
      "author": {
        "name": "EventStore"
      },
      "summary": "event-type",
      "links": [
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/1",
          "relation": "edit"
        },
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/1",
          "relation": "alternate"
        }
      ]
    },
    {
      "title": "0@alphabet",
      "id": "http://127.0.0.1:2113/streams/alphabet/0",
      "updated": "2018-08-21T09:53:46.869716Z",
      "author": {
        "name": "EventStore"
      },
      "summary": "event-type",
      "links": [
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/0",
          "relation": "edit"
        },
        {
          "uri": "http://127.0.0.1:2113/streams/alphabet/0",
          "relation": "alternate"
        }
      ]
    }
  ]
}

// Make sure to add code blocks to your code group

You then follow previous links until you are back to the head of the stream, where you can continue reading events in real time by polling the previous link.

TIP

All links except the head link are fully cacheable as you can see in the HTTP header Cache-Control: max-age=31536000, public. This is important when discussing intermediaries and performance as you commonly replay a stream from storage. You should never bookmark links aside from the head of the stream resource, and always follow links. We may in the future change how internal links work, and bookmarking links other than the head may break.

# Reading all events

$all is a special paged stream for all events. You can use the same paged form of reading described above to read all events for a node by pointing the stream at /streams/$all. As it's a stream like any other, you can perform all operations, except posting to it.

TIP

To access the $all stream, you must use admin details. Find more information on the security page.

curl -i http://127.0.0.1:2113/streams/%24all \
    -H "Accept:application/vnd.eventstore.atom+json" -u admin:changeit

HTTP/1.1 200 OK
Access-Control-Allow-Methods: POST, DELETE, GET, GET, OPTIONS
Access-Control-Allow-Headers: Content-Type, X-Requested-With, X-PINGOTHER, Authorization, ES-LongPoll, ES-ExpectedVersion, ES-EventId, ES-EventType, ES-RequiresMaster, ES-HardDelete, ES-ResolveLinkTo, ES-ExpectedVersion
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: Location, ES-Position
Cache-Control: max-age=0, no-cache, must-revalidate
Vary: Accept
ETag: "25159393;248368668"
Content-Type: application/vnd.eventstore.atom+json; charset=utf-8
Server: Mono-HTTPAPI/1.0
Date: Fri, 13 Mar 2015 16:19:09 GMT
Content-Length: 12157
Keep-Alive: timeout=15,max=100

{
  "title": "All events",
  "id": "<http://127.0.0.1:2113/streams/%24all">,
  "updated": "2015-03-13T16:19:06.548415Z",
  "author": {
    "name": "EventStore"
  },
  "headOfStream": false,
  "links": [
    {
      "uri": "http://127.0.0.1:2113/streams/%24all",
      "relation": "self"
    },
    {
      "uri": "http://127.0.0.1:2113/streams/%24all/head/backward/20",
      "relation": "first"
    },
    {
      "uri": "http://127.0.0.1:2113/streams/%24all/00000000000000000000000000000000/forward/20",
      "relation": "last"
    },
    {
      "uri": "http://127.0.0.1:2113/streams/%24all/00000000017BC0D000000000017BC0D0/backward/20",
      "relation": "next"
    },
    {
      "uri": "http://127.0.0.1:2113/streams/%24all/0000000001801EBF0000000001801EBF/forward/20",
      "relation": "previous"
    },
    {
      "uri": "http://127.0.0.1:2113/streams/%24all/metadata",
      "relation": "metadata"
    }
  ],
  "entries": []
}

// Make sure to add code blocks to your code group

# Conditional GETs

The head link supports conditional GETs with the use of ETAGS (opens new window), a well-known HTTP construct. You can include the ETAG of your last request and issue a conditional GET to the server. If nothing has changed, it won't return the full feed. For example the earlier response has an ETAG:

HTTP/1.1 200 OK
Access-Control-Allow-Methods: POST, DELETE, GET, OPTIONS
Access-Control-Allow-Headers: Content-Type, X-Requested-With, X-Forwarded-Host, X-Forwarded-Prefix, X-PINGOTHER, Authorization, ES-LongPoll, ES-ExpectedVersion, ES-EventId, ES-EventType, ES-RequiresMaster, ES-HardDelete, ES-ResolveLinkTos
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: Location, ES-Position, ES-CurrentVersion
Cache-Control: max-age=0, no-cache, must-revalidate
Vary: Accept
ETag: "26;-2060438500"
Content-Type: application/vnd.eventstore.atom+json; charset=utf-8
Server: Mono-HTTPAPI/1.0
Date: Tue, 21 Aug 2018 10:12:31 GMT
Content-Length: 10727
Keep-Alive: timeout=15,max=100

You can use this in your next request when polling the stream for changes by putting it in the If-None-Match header. This tells the server to check if the response is the one you already know and returning a '304 not modified' response. If the tags have changed, the server returns a '200 OK' response. You can use this method to optimise your application by not sending large streams if there are no changes.

curl -i http://127.0.0.1:2113/streams/alphabet \
    -H "Accept:application/vnd.eventstore.atom+json" \
    -H "If-None-Match:26;-2060438500"

HTTP/1.1 304 Not Modified
Access-Control-Allow-Methods: POST, DELETE, GET, OPTIONS
Access-Control-Allow-Headers: Content-Type, X-Requested-With, X-Forwarded-Host, X-Forwarded-Prefix, X-PINGOTHER, Authorization, ES-LongPoll, ES-ExpectedVersion, ES-EventId, ES-EventType, ES-RequiresMaster, ES-HardDelete, ES-ResolveLinkTos
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: Location, ES-Position, ES-CurrentVersion
Content-Type: text/plain; charset=utf-8
Server: Mono-HTTPAPI/1.0
Date: Tue, 21 Aug 2018 12:07:35 GMT
Content-Length: 0
Keep-Alive: timeout=15,max=100

// Make sure to add code blocks to your code group

TIP

You create Etags using the version of the stream and the media type of the stream you are reading. You can't read an Etag from a stream in one media type and use it with another media type.

# Embedding data into streams in JSON format

So far in this guide, the feeds returned have contained links that refer to the actual event data. This is normally a preferable mechanism for several reasons:

They can be in a different media type than the feed, and you can negotiate them separately from the feed itself (for example, the feed in JSON, the event in XML). You can cache the event data separately from the feed, and you can point it to different feeds. If you use a linkTo() in your projection this is what happens in your atom feeds.
If you are using JSON, you can embed the events into the atom feed events. This can help cut down on the number of requests in some situations, but the messages are larger.

There are ways of embedding events and further metadata into your stream by using the embed parameter.

# Rich embed mode

The rich embed mode returns more properties about the event (eventtype, streamid, position, and so on) as you can see in the following request.

curl -i -H "Accept:application/vnd.eventstore.atom+json" \
    "http://127.0.0.1:2113/streams/newstream?embed=rich"

HTTP/1.1 200 OK
Access-Control-Allow-Methods: POST, DELETE, GET, OPTIONS
Access-Control-Allow-Headers: Content-Type, X-Requested-With, X-PINGOTHER, Authorization, ES-LongPoll, ES-ExpectedVersion, ES-EventId, ES-EventType, ES-RequiresMaster, ES-HardDelete, ES-ResolveLinkTo, ES-ExpectedVersion
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: Location, ES-Position
Cache-Control: max-age=0, no-cache, must-revalidate
Vary: Accept
ETag: "0;248368668"
Content-Type: application/vnd.eventstore.atom+json; charset=utf-8
Server: Mono-HTTPAPI/1.0
Date: Fri, 13 Mar 2015 16:30:57 GMT
Content-Length: 1570
Keep-Alive: timeout=15,max=100

{
  "title": "Event stream 'newstream'",
  "id": "<http://127.0.0.1:2113/streams/newstream">,
  "updated": "2015-03-13T12:13:42.492473Z",
  "streamId": "newstream",
  "author": {
    "name": "EventStore"
  },
  "headOfStream": true,
  "selfUrl": "<http://127.0.0.1:2113/streams/newstream">,
  "eTag": "0;248368668",
  "links": [
    {
      "uri": "http://127.0.0.1:2113/streams/newstream",
      "relation": "self"
    },
    {
      "uri": "http://127.0.0.1:2113/streams/newstream/head/backward/20",
      "relation": "first"
    },
    {
      "uri": "http://127.0.0.1:2113/streams/newstream/1/forward/20",
      "relation": "previous"
    },
    {
      "uri": "http://127.0.0.1:2113/streams/newstream/metadata",
      "relation": "metadata"
    }
  ],
  "entries": [
    {
      "eventId": "fbf4a1a1-b4a3-4dfe-a01f-ec52c34e16e4",
      "eventType": "event-type",
      "eventNumber": 0,
      "streamId": "newstream",
      "isJson": true,
      "isMetaData": false,
      "isLinkMetaData": false,
      "positionEventNumber": 0,
      "positionStreamId": "newstream",
      "title": "0@newstream",
      "id": "<http://127.0.0.1:2113/streams/newstream/0">,
      "updated": "2015-03-13T12:13:42.492473Z",
      "author": {
        "name": "EventStore"
      },
      "summary": "event-type",
      "links": [
        {
          "uri": "http://127.0.0.1:2113/streams/newstream/0",
          "relation": "edit"
        },
        {
          "uri": "http://127.0.0.1:2113/streams/newstream/0",
          "relation": "alternate"
        }
      ]
    }
  ]
}

// Make sure to add code blocks to your code group

# Body embed mode

The body embed mode returns the JSON/XML body of the events into the feed as well, depending on the type of the feed. You can see this in the request below:

curl -i -H "Accept:application/vnd.eventstore.atom+json" \
    "http://127.0.0.1:2113/streams/newstream?embed=body"

HTTP/1.1 200 OK
Access-Control-Allow-Methods: POST, DELETE, GET, OPTIONS
Access-Control-Allow-Headers: Content-Type, X-Requested-With, X-PINGOTHER, Authorization, ES-LongPoll, ES-ExpectedVersion, ES-EventId, ES-EventType, ES-RequiresMaster, ES-HardDelete, ES-ResolveLinkTo, ES-ExpectedVersion
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: Location, ES-Position
Cache-Control: max-age=0, no-cache, must-revalidate
Vary: Accept
ETag: "0;248368668"
Content-Type: application/vnd.eventstore.atom+json; charset=utf-8
Server: Mono-HTTPAPI/1.0
Date: Fri, 13 Mar 2015 16:32:06 GMT
Content-Length: 1608
Keep-Alive: timeout=15,max=100

{
  "title": "Event stream 'newstream'",
  "id": "<http://127.0.0.1:2113/streams/newstream">,
  "updated": "2015-03-13T12:13:42.492473Z",
  "streamId": "newstream",
  "author": {
    "name": "EventStore"
  },
  "headOfStream": true,
  "selfUrl": "<http://127.0.0.1:2113/streams/newstream">,
  "eTag": "0;248368668",
  "links": [
    {
      "uri": "http://127.0.0.1:2113/streams/newstream",
      "relation": "self"
    },
    {
      "uri": "http://127.0.0.1:2113/streams/newstream/head/backward/20",
      "relation": "first"
    },
    {
      "uri": "http://127.0.0.1:2113/streams/newstream/1/forward/20",
      "relation": "previous"
    },
    {
      "uri": "http://127.0.0.1:2113/streams/newstream/metadata",
      "relation": "metadata"
    }
  ],
  "entries": \[
    {
      "eventId": "fbf4a1a1-b4a3-4dfe-a01f-ec52c34e16e4",
      "eventType": "event-type",
      "eventNumber": 0,
      "data": "{\\n  "a": "1"\\n}",
      "streamId": "newstream",
      "isJson": true,
      "isMetaData": false,
      "isLinkMetaData": false,
      "positionEventNumber": 0,
      "positionStreamId": "newstream",
      "title": "0@newstream",
      "id": "<http://127.0.0.1:2113/streams/newstream/0">,
      "updated": "2015-03-13T12:13:42.492473Z",
      "author": {
        "name": "EventStore"
      },
      "summary": "event-type",
      "links": [
        {
          "uri": "http://127.0.0.1:2113/streams/newstream/0",
          "relation": "edit"
        },
        {
          "uri": "http://127.0.0.1:2113/streams/newstream/0",
          "relation": "alternate"
        }
      ]
    }
  ]
}

// Make sure to add code blocks to your code group

# Variants of body embed mode

Two other modes are variants of body:

PrettyBody tries to reformat the JSON to make it "pretty to read".
TryHarder works harder to try to parse and reformat the JSON from an event to return it in the feed. These do not include further information and are focused on how the feed looks.

# Embedding data into streams in XML format

The XML format embeds no additional data, as only JSON supports embedding.

curl -i -H "Accept:application/atom+xml" \
    "http://127.0.0.1:2113/streams/newstream?embed=body"

HTTP/1.1 200 OK
Access-Control-Allow-Methods: POST, DELETE, GET, OPTIONS
Access-Control-Allow-Headers: Content-Type, X-Requested-With, X-PINGOTHER, Authorization, ES-LongPoll, ES-ExpectedVersion, ES-EventId, ES-EventType, ES-RequiresMaster, ES-HardDelete, ES-ResolveLinkTo, ES-ExpectedVersion
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: Location, ES-Position
Cache-Control: max-age=0, no-cache, must-revalidate
Vary: Accept
ETag: "0;-1296467268"
Content-Type: application/atom+xml; charset=utf-8
Server: Mono-HTTPAPI/1.0
Date: Fri, 13 Mar 2015 16:32:56 GMT
Content-Length: 929
Keep-Alive: timeout=15,max=100
<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
   <title>Event stream 'newstream'</title>
   <id>http://127.0.0.1:2113/streams/newstream</id>
   <updated>2013-06-29T15:12:53.570125Z</updated>
   <author>
      <name>EventStore</name>
   </author>
   <link href="http://127.0.0.1:2113/streams/newstream" rel="self" />
   <link href="http://127.0.0.1:2113/streams/newstream/head/backward/20" rel="first" />
   <link href="http://127.0.0.1:2113/streams/newstream/0/forward/20" rel="last" />
   <link href="http://127.0.0.1:2113/streams/newstream/1/forward/20" rel="previous" />
   <link href="http://127.0.0.1:2113/streams/newstream/metadata" rel="metadata" />
   <entry>
      <title>0@newstream</title>
      <id>http://127.0.0.1:2113/streams/newstream/0</id>
      <updated>2013-06-29T15:12:53.570125Z</updated>
      <author>
         <name>EventStore</name>
      </author>
      <summary>event-type</summary>
      <link href="http://127.0.0.1:2113/streams/newstream/0" rel="edit" />
      <link href="http://127.0.0.1:2113/streams/newstream/0" rel="alternate" />
   </entry>
</feed>

// Make sure to add code blocks to your code group

← Writing Events Deleting a stream →