Federation API Conventions
All endpoints must start with
/federation/
All path segments must be in kebab-case, and only consist of alphanumeric characters. The name the field in the record must be the same name in camelCase.
There must be exactly one segment after
/federation/
, so/federation/foo
is valid, but/federation/foo/bar
is not.All endpoints must be
POST
.No query query params or captured path params, all information that needs to go must go in body.
All responses must be
200 OK
, domain specific failures (e.g. the conversation doesn’t exist) must be indicated as a Sum type. Unhandled failures can be 5xx, an endpoint not being implemented will of course return 404. But we shouldn’t pile onto these. This keeps the federator simple.Accept only json, respond with only json. Maybe we can think of changing this in future. But as of now, the federator hardcodes application/json as the content type of the body.
Ensure that paths don’t collide between brig and galley federation API, this will be very helpful when we merge brig and galley.
The name of the path segment after
/federation/
must be either<imperative-verb>-<object>
oron-<subject>-<past-tense-verb>
, e.g.get-conversations
oron-conversation-created
.How to decide which one to use:
If the request is supposed to ask for information/change from another backend which has authority over that information, like send a message or leave a conversation, then use the first format like
send-message
orleave-conversation
.If the request is supposed to notify a backend about something the caller of this request has authority on, like a conversation got created, or a message is sent, then use the second format like
on-conversation-created
oron-message-sent
A call graph of the API endpoints the can call to federation members is included below.