ibanawx/prooph-event-store-rest-api-bundle

Make Prooph Event Store streams accessible over a REST API.

v1.0.0 2016-10-26 16:08 UTC

This package is not auto-updated.

Last update: 2025-01-04 21:52:40 UTC


README

1. Download

composer require ibanawx/prooph-event-store-rest-api-bundle

2. Bundle Registration

Register the following bundles in your Symfony kernel:

  1. Prooph\Bundle\EventStore\ProophEventStoreBundle
  2. Ibanawx\Bundle\Prooph\EventStore\RestApiBundle\ProophEventStoreRestApiBundle

3. Import Routes

# app/config/routing.yml

prooph_event_store:
  resource: '@ProophEventStoreRestApiBundle/Resources/config/routing.yml'
  prefix: /event-store

The prefix option above is optional but useful if you'd like to separate this bundles routes from the other routes in your application.

Configuration

# app/config/config.yml

prooph_event_store:
  stores:
    default:
      adapter: event_store_adapter_service_id

prooph_event_store_rest_api:
  event_store:
    name: default
  formatters:
    stream: ~
    event: ~

For more information on configuring the prooph_event_store bundle click here.

prooph_event_store_rest_api

Usage

All HTTP requests to the REST API must contain at least an Accept header specifying the content type you accept. The accepted content type is directly related to the output content type of the formatter.

Getting a Stream

Request Placeholders:

  • streamName: The name of the stream.
  • minVersion: The minimum event version that will appear in the stream.

Succesful Response

By default, a response with an application/json content type will be returned. This is because the default formatter formats the stream to JSON.

The default JSON formatter closely follows The Atom Syndication Format but does not match it perfectly.

Let's say you have a user stream with 0 events. Sending a GET request to http://site.com/streams/user/0 will respond with this:

{
  "id": "http://site.com/streams/user/0",
  "title": "user stream",
  "links": [],
  "entries": []
}

Let's say you have a user stream with 2 events. Sending a GET request to http://site.com/streams/user/0 will respond with this:

{
  "id": "http://site.com/streams/user/0",
  "title": "user stream",
  "links": [
    {
      "uri": "http://site.com/streams/user/2",
      "relation": "next"
    }
  ],
  "entries": [
    {
      "id": "http://site.com/streams/user/events/0",
      "title": "0@user",
      "updated": "2016-10-25 21:41:03",
      "content": {
        "id": "44c552d3-0868-4e36-9b9b-160bad558d89",
        "name": "UserSignedUp",
        "version": 0,
        "metadata": {},
        "createdAt": "2016-10-25 21:41:03",
        "payload": {}
      }
    },
    {
      "id": "http://site.com/streams/user/events/1",
      "title": "1@user",
      "updated": "2016-10-25 21:43:56",
      "content": {
        "id": "e902f95f-60d0-4bc5-afcf-13eddc6eed23",
        "name": "UserSignedUp",
        "version": 1,
        "metadata": {},
        "createdAt": "2016-10-25 21:43:56",
        "payload": {}
      }
    }
  ]
}

Stream Navigation

The default JSON representation of a stream allows you to navigate through the stream using hypermedia links.

If the user stream contained 42 events (versions 0 - 41), sending a GET request to http://site.com/streams/user/0 would respond with the following next link:

{
  "uri": "http://site.com/streams/user/42",
  "relation": "next"
}

To get the next event(s) in this stream you would poll the next URI.

If the stream has no events from the minimum version you specified there will be no next link present in the stream.

Getting a Stream Event

Request Placeholders

  • streamName: The name of the stream.
  • version: The version of the event.

Customization

Formatters

A formatter takes a stream or an event and formats it into a string which is then sent back as the body of the response.

Stream Formatter

This formatter is called when getting a stream.

  1. Implement Ibanawx\Bundle\Prooph\EventStore\RestApiBundle\Formatter\StreamFormatter
  2. Define your custom formatter as a service in the dependency injection container.
  3. Set the stream formatter to the service ID in your app/config/config.yml file.

Methods to Implement

  • getOutputContentType(): Returns a string specifying the content type of the data which the formatter returns.
  • format(): Returns a string representation of a stream.

Stream Event Formatter

This formatter is called when getting a single stream event.

  1. Implement Ibanawx\Bundle\Prooph\EventStore\RestApiBundle\Formatter\StreamEventFormatter
  2. Define your custom formatter as a service in the dependency injection container.
  3. Set the stream event formatter to the service ID in your app/config/config.yml file.

Methods to Implement

  • getOutputContentType(): Returns a string specifying the content type of the data which the formatter returns.
  • format(): Returns a string representation of a stream event.