# 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>` or `on-<subject>-<past-tense-verb>`, e.g.
  `get-conversations` or `on-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` or
    `leave-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` or
    `on-message-sent`

  A call graph of the API endpoints the can call to federation members is included below.

  ![Federation call graph](FedCalls.png)