Update docs about event types #454
Conversation
Codecov Report
@@ Coverage Diff @@
## master #454 +/- ##
==========================================
+ Coverage 66.17% 66.17% +<.01%
==========================================
Files 32 32
Lines 1883 1892 +9
==========================================
+ Hits 1246 1252 +6
- Misses 585 587 +2
- Partials 52 53 +1
Continue to review full report at Codecov.
|
mthenw
force-pushed
the
et-docs
branch
7 times, most recently
from
73aa3ef
to
f18660e
Compare
There was a problem hiding this comment.
@mthenw Thanks for writing the docs on this. Really appreciate you taking the time.
I'm concerned that the Events API section will be confusing to users as it switches between conceptual elements, details about subscriptions, and then API reference about the Events API itself.
I propose limiting this section of the docs more to API reference. How about the following structure of the Events API portion:
- How to Emit an Event (API reference showing the HTTP mechanism for emitting an event).
- CloudEvents behavior when an Event is received -- what does the payload turn it to, and how is it matched to a subscription?
The other stuff we should put either in a conceptual section of the docs (What are Events, EventTypes, Subscriptions, and Functions, and how do they interact?) or in more detailed reference material about the subjects themselves (e.g. a Subscriptions page that dives deeper into sync vs. async, an Event Types page that discusses authorization, etc.). These sections don't even need to be implemented today, though we do need to prioritize it in the very near term.
Thoughts? I'm not trying to make the perfect the enemy of the good, so let me know if I'm off base.
| name: | ||
| $ref: '#/components/schemas/EventTypeName' | ||
| authorizerId: | ||
| $ref: '#/components/schemas/FunctionID' |
There was a problem hiding this comment.
Does this mean authorizerId is a required property? Do we mark things as optional?
There was a problem hiding this comment.
I added list of required fields for every request payload.
docs/api.md
Outdated
|
|
||
| #### Event Data Type | ||
| Event Gateway support two subscription types: `async` and `sync`. |
docs/api.md
Outdated
|
|
||
| ### Authorization | ||
|
|
||
| Event Type can define authorizer function that will be called before calling a subscribed function. Authorizer function is a function registered in Function Discovery beforehand. |
There was a problem hiding this comment.
Function Discovery --> Event Gateway ?
docs/api.md
Outdated
|
|
||
| All data that passes through the Event Gateway is formatted as a CloudEvent, based on [CloudEvents v0.1 schema](https://github.com/cloudevents/spec/blob/master/spec.md): | ||
| Event Registry is a single source of truth about events occuring in the space. Every event emitted to a space has to have type registered beforehand. |
There was a problem hiding this comment.
This section is confusing to me. Where/what is the Event Registry?
EDIT: I see now. Added comment below on it.
docs/api.md
Outdated
|
|
||
| The Event Gateway exposes a RESTful JSON configuration API. By default Configuration API runs on `:4001` port. | ||
|
|
||
| ### Event Registry |
There was a problem hiding this comment.
IMO, "Event Registry" is more confusing than just "Event Types" or "Event Types Resource Actions".
"Event Registry" seems like a set of functionality around Events beyond CRUD actions on a single REST resource.
docs/api.md
Outdated
|
|
||
| The Event Gateway exposes a RESTful JSON configuration API. By default Configuration API runs on `:4001` port. | ||
|
|
||
| ### Function Discovery |
There was a problem hiding this comment.
Same note on "Function Discovery" as on "Event Registry" above.
docs/api.md
Outdated
| * `202 Accepted` | ||
| * `202 Accepted` - if there is no `sync` subscription. Otherwise, status code is controlled by function synchronously subscribed on this endpoint. | ||
|
|
||
| ### Legacy Mode |
There was a problem hiding this comment.
Should we just delete Legacy Mode from the docs? We can continue to support it for a few versions but aim to deprecate.
There was a problem hiding this comment.
I think it should be here as long as we support it. I will add deprecation note.
| @@ -1,40 +0,0 @@ | |||
| openapi: "3.0.1" | |||
There was a problem hiding this comment.
I removed this spec as it doesn't really provide any value. @alexdebrie thoughts?
|
@alexdebrie please take a look again. I refactored it a bit. |
Docs about event types and Events API authorization