Federation API r0 megathread

[turt2live]

This is a list of all the endpoints that are currently listed as "federation" (server-to-server), but have not been specced. Follow this issue for updates to the plan and progress.

---

"Ambitious goal"

This all the stuff that qualifies for the running-name of "Travis' ambitious goal". Targeting very early August for spec.

Sections (review&fix):

• PDUs and EDUs - Improve documentation around EDUs and PDUs  #1463
• Server Discovery - Spec Host and SNI headers for federated calls (including the media repo) #1161, Federation: Document the Host header; Clarify how literal IP addresses are handled #1479
• State resolution
• Authentication - Define authorization requirements on federation swagger APIs #1481
• Presence - Document how presence EDUs work between servers #1482
• Signing
• General cleanup of sections - General clean up on the s2s spec #1478
• Typing notifications - Document how typing notifications work over federation #1483
• Read receipts - Document how read receipts work over federation #1484

Endpoints:

• PUT /send/$txnId - Improve documentation on how Transactions work #1461
• GET /pull Unused endpoint
• GET /event/$eventId - Document event retrieval endpoints in more detail #1472
• GET /state/$context - Document event retrieval endpoints in more detail #1472
• GET /state_ids/$roomId - spec /state_ids #1451, Document event retrieval endpoints in more detail #1472
• GET /backfill/$context - Improve documentation for backfilling rooms #1469
• GET /query/$queryType - spec profile query #1404, Combine all queries into their own section #1443
• GET /make_join/$context/$userId - Improve the documentation for joining rooms #1428
• GET /make_leave/$context/$userId - s2s: spec how to leave a room over federation #1401, Document how leaving rooms/rejecting invites over federation works #1455
• PUT /send_leave/$roomId/$eventId - s2s: spec how to leave a room over federation #1401, Document how leaving rooms/rejecting invites over federation works #1455
• PUT /send_join/$roomId/$eventId - Improve the documentation for joining rooms #1428
• PUT /invite/$context/$eventId - Improve documentation for how non-third party invites work #1450
• GET /event_auth/$context/$eventId - federation /event_auth is undocumented #1274, Document /event_auth and /query_auth #1475
• POST /query_auth/$context/$eventId - Document /event_auth and /query_auth #1475
• POST /get_missing_events/$roomId - get_missing_events API is undocumented #1385, Improve documentation for backfilling rooms #1469
• GET /publicRooms - Document the /publicRooms endpoint for federation #1477
• GET /version
• GET /key/v2/query/$serverName/$keyId - Improve the server key exchange portion of the s2s specification #1423
• POST /key/v2/query - Improve the server key exchange portion of the s2s specification #1423
• GET /key/v2/server/$keyId - Improve the server key exchange portion of the s2s specification #1423

Media/Content Repository

Targeting August for spec.

Issues:

• https://github.com/matrix-org/matrix-doc/issues/1341
• How to download content from remotes - Mention how the content repository works over federation #1493

Third party identifiers

Targeting early August for spec.

Issues:

• Improve documentation of how third party invites work #1366
• Spec include_all_networks and third_party_instance_id on federation and c2s /publicRooms #1476

Endpoints:

• PUT /exchange_third_party_invite/$roomId - Clarify how third party invites work #1505
• POST /3pid/onbind - /federation/v1/3pid/onbind is undocumented #1422, Clarify how third party invites work #1505

End-to-end encryption

Targeting early August for spec (synchronized with client/server documentation).

Issues:

• End-to-End Crypto (SPEC-162) #501

Endpoints:

• POST /user/keys/query - Spec federation /user/* endpoints #1438
• GET /user/devices/$userId - Spec federation /user/* endpoints #1438
• POST /user/keys/claim - Spec federation /user/* endpoints #1438

The device list stuff (#1212) is fairly subtle and would need to be specced alongside this, i suspect (but should be a matter of porting the necessary stuff out of the prop and into the spec) --matthew

OpenID

Targeting August for spec (synchronized with client/server documentation).

Issues:

• spec openid API #857
• Move OpenID to its own namespace #1115

Endpoints:

• GET /openid/userinfo - Document OpenID in the client-server and server-server APIs #1494

Groups

Targeting August for spec (synchronized with client/server documentation).

Note: Groups have been cut from the r0 release, and will be worked out post-r0

Issues:

• Add groups stuff to spec #971

Endpoints:

• GET /groups/$groupId/profile
• POST /groups/$groupId/profile
• GET /groups/$groupId/summary
• GET /groups/$groupId/rooms
• POST /groups/$groupId/room/$roomId
• DELETE /groups/$groupId/room/$roomId
• POST /groups/$groupId/room/$roomId/config/$configKey
• GET /groups/$groupId/users
• GET /groups/$groupId/invited_users
• POST /groups/$groupId/users/$userId/invite
• POST /groups/$groupId/users/$userId/accept_invite
• POST /groups/$groupId/users/$userId/join
• POST /groups/$groupId/users/$userId/remove
• POST /groups/local/$groupId/users/$userId/invite
• POST /groups/local/$groupId/users/$userId/remove
• POST /groups/$groupId/renew_attestation/$userId
• POST /groups/$groupId/summary/rooms/$roomId
• POST /groups/$groupId/summary/categories/$category/rooms/$roomId
• DELETE /groups/$groupId/summary/rooms/$roomId
• DELETE /groups/$groupId/summary/categories/$category/rooms/$roomId
• GET /groups/$groupdId/categories
• GET /groups/$groupId/categories/$category
• POST /groups/$groupId/categories/$category
• DELETE /groups/$groupId/categories/$category
• GET /groups/$groupId/roles
• GET /groups/$groupId/roles/$roleId
• POST /groups/$groupId/roles/$roleId
• DELETE /groups/$groupId/roles/$roleId
• POST /groups/$groupId/summary/users/$userId
• POST /groups/$groupId/summary/roles/$roleId/users/$userId
• DELETE /groups/$groupId/summary/users/$userId
• DELETE /groups/$groupId/summary/roles/$roleId/users/$userId
• POST /get_groups_publicised
• PUT /groups/$groupId/settings/m.join_policy

[uhoreg]

Most of E2E should be covered by #1284 and #1420

[turt2live]

As far as I can tell, both of those only cover the client/server side of things. It'd be awesome if they also covered the s2s side too :)

[uhoreg]

Ah, right. Yes, they're only CS.

[turt2live]

I've updated the OP: Everything is done except for groups. Groups are being considered post-r0 pending some potential changes. This issue is now a placeholder for "we need to actually cut a release".

[turt2live]

The reminder for actually cutting an r0 is now at #1805