notifications and REST

[pvdbosch]

In GitLab by @pvdbosch on Aug 9, 2018, 11:38

experiences from eBox? (Willem)

[pvdbosch]

In GitLab by @pvdbosch on Aug 9, 2018, 12:31

assigned to @wsalembi

[VirginieHayot]

REQUIREMENTS

• Must be usable in both a broker architecure as a service architecture
• Reusable common schemas for different institutions

OVERVIEW

REVIEW

event.json

• Versioning?
• eventId = UUID, why so strict in schema?
• Publisher/creator URN, why enforce URN? Part of CN from X509 certificate?
• DestinationTopic: rename (too broker-like)

content.json

• Versioning? in filename: content-v1.json?
• Add possibilities for payload encryption and/or signature (JWS)

custom-payload.json

• Versioning? in filename: custom-payload-v1.json? A more explicit field, to make event designers think of versioning?

General questions/remarks

• How would subscribers know the different schemas? Schema repository?
• How could an encryption layer be added? Standardize this?
• Add examples on 2 archetypes: "Event notifications" and "Event-Carried State Transfer": https://martinfowler.com/articles/201701-event-driven.html
• Add examples for the 3 types of architectures (independent from the 2 previous archetypes):
• Broker: no envelope needed
• Pull REST service (classic service paradigm): add swagger + support to return multiple events at once + acknowledge
• Push REST service (webhooks): add swagger + acknowledge
• Add rules about additionalProperties
• How is subscription done for SocSec? Could standardize this too.

REFERENCES

https://docs.aws.amazon.com/sns/index.html
https://refubium.fu-berlin.de/bitstream/handle/fub188/4008/03_hinze_chapter03.pdf?sequence=4&isAllowed=y
http://www.marco.panizza.name/dispenseTM/slides/exerc/eventNotifier/eventNotifier.html

[pvdbosch]

Some thoughts:

• for both archetypes, at the very least an "eventId" and "eventType" (aka destinationTopic) would be needed
• the eventType could imply the JSON schema(s) and version of the payload instead of linking these to each event
  • zalando makes distinction between event type metadata and event metadata
• having two levels of headers seems a bit complex, I think we could manage with a single extensible header. "actor" and "concernedEntities" are business data that may not be generally applicable.

[bertvannuffelen]

In the second OSLO session on API guidelines the challenge of data synchronisation has been sketched and introduced:

• https://data.vlaanderen.be/standaarden/standaarden-in-ontwikkeling/api-guidelines/api-guidelines-index.html

• https://data.vlaanderen.be/standaarden/standaarden-in-ontwikkeling/api-guidelines/OSLO%20API%20Guidelines%20-%20Workshop%202%2019_03_20%20-%20Verslag.docx

• https://data.vlaanderen.be/standaarden/standaarden-in-ontwikkeling/api-guidelines/19032020%20-%20API%20guidelines%20WS2.pptx

[pvdbosch]

OpenAPI 3.1 will support specifying schemas for webhooks: https://github.com/OAI/OpenAPI-Specification/blob/v3.1.0-dev/versions/3.1.0.md#oasWebhooks

[pvdbosch]

The CloudEvents specification looks quite interesting: https://github.com/cloudevents/spec
Maybe we could adopt it?

It's a a quite uncomplicated specification for events. It defines a conceptual model, protocol bindings to JSON and HTTP, and also a more formal specification of webhooks.

[VirginieHayot]

In the second OSLO session on API guidelines the challenge of data synchronisation has been sketched and introduced:

* https://data.vlaanderen.be/standaarden/standaarden-in-ontwikkeling/api-guidelines/api-guidelines-index.html

* https://data.vlaanderen.be/standaarden/standaarden-in-ontwikkeling/api-guidelines/OSLO%20API%20Guidelines%20-%20Workshop%202%2019_03_20%20-%20Verslag.docx

* https://data.vlaanderen.be/standaarden/standaarden-in-ontwikkeling/api-guidelines/19032020%20-%20API%20guidelines%20WS2.pptx

Basic topics

• Protocol/architectuur
  ** pull vs push
  ** garantuee of sequence
  ** single or bulk accumulation
  ** fine-grained subscription
  ** security? (not mentioned in these docs)

• Format/structure
  ** Sequence (time or number based)
  ** Content (id or id/object or id/delta)

Interesting links from these presentations:
JSON based

• https://jsonfeed.org/version/1

XML based

• https://en.wikipedia.org/wiki/Atom_(Web_standard)

• https://tools.ietf.org/html/rfc5023

• https://validator.w3.org/feed/docs/atom.html

• https://validator.w3.org/feed/docs/rss2.html#whatIsRss

[bertvannuffelen]

A validator for cloudevents: https://joinup.ec.europa.eu/solution/interoperability-test-bed/news/new-cloudevents-validation-service

[pvdbosch]

merged PR with CloudEvents. For further standardization other issues can be opened. We probably best wait until we a WG member has gathered more real-world experience.