Advanced Usage

Rate Limiting

The returned HTTP headers of any API request show your current rate limit status.

We can do a GET request to our order projection:

curl -i \
  --header "Serialized-Access-Key: <YOUR_ACCESS_KEY>" \
  --header "Serialized-Secret-Access-Key: <YOUR_SECRET_ACCESS_KEY>" \
  https://api.serialized.io/projections/single/orders/<orderId>

HTTP/1.1 200 OK
Content-Type: application/json
Serialized-RateLimit-Limit: 10000
Serialized-RateLimit-Remaining: 9999
Serialized-RateLimit-Reset: 1506939198
...

{
  "aggregateId": "..."
}
Header Name Description
Serialized-RateLimit-Limit The maximum number of requests you’re permitted to make per hour.
Serialized-RateLimit-Remaining The number of requests remaining in the current rate limit window.
Serialized-RateLimit-Reset The time at which the current rate limit window resets in UTC epoch seconds.

If you exceed the rate limit, an error response returns:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Serialized-RateLimit-Limit: 10000
Serialized-RateLimit-Remaining: 0
Serialized-RateLimit-Reset: 1506939198

{
  "code": 429,
  "message": "You have requested this resource too often. Slow down."
}

Conditional requests

To minimize bandwidth usage, the response from /aggregates/ and /projections/ returns the ETag header. You can use the value of this header to make subsequent requests to that resources using the If-None-Match header. If the resource has not changed, the server will return a 304 Not Modified.

curl -i \
  --header "Serialized-Access-Key: <YOUR_ACCESS_KEY>" \
  --header "Serialized-Secret-Access-Key: <YOUR_SECRET_ACCESS_KEY>" \
  https://api.serialized.io/aggregates/order/<orderId>

HTTP/1.1 200 OK
Content-Type: application/json
Date: Tue, 19 Sep 2017 14:04:15 GMT
ETag: "eccbc87e4b5ce2fe28308fd9f2a7baf3"
...

{
  "aggregateId": "..."
}
curl -i \
  --header "Serialized-Access-Key: <YOUR_ACCESS_KEY>" \
  --header "Serialized-Secret-Access-Key: <YOUR_SECRET_ACCESS_KEY>" \
  --header "If-None-Match: \"eccbc87e4b5ce2fe28308fd9f2a7baf3\"" \
  https://api.serialized.io/aggregates/order/<orderId>

HTTP/1.1 304 Not Modified
Date: Tue, 19 Sep 2017 14:04:15 GMT
ETag: "eccbc87e4b5ce2fe28308fd9f2a7baf3"
...

Encrypting event data

Need to store personal or sensitive data in your events? We have a solution for that too! You can populate the field encryptedData, which is reserved for this kind of client-side encrypted data. This field will not be processed in any way and can contain pretty much anything packed into a string. Preferably you encrypt a JSON payload using symmetric encryption. Remember to keep the secret key safe! As you are not sharing the key with us, there’s no way we can help you recover it or access your encrypted data if you loose it. Note that the field is limited to max 65535 bytes.

Example event payload utilizing the encryptedData field:

{
  "aggregateId": "723ecfce-14e9-4889-98d5-a3d0ad54912f",
  "events": [
    {
      "eventId": "127b80b5-4a05-4774-b870-1c9a2e2a27a3",
      "eventType": "OrderPlacedEvent",
      "encryptedData": "9cb2948ea01673aea153ef5a9618d4debf2c90385ec958470fc13...",
      "data": {
        "customerId": "some-test-id-1",
        "orderAmount": 12345
      }
    }
  ]
}