From 7d34995ece2e057fbcb75b4a559a88f043b85095 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 31 Aug 2018 15:35:32 -0600 Subject: [PATCH] It's actually an "identity server implementing the Identity Service API" Also add a note about appservices being special. --- api/client-server/administrative_contact.yaml | 4 ++-- api/client-server/create_room.yaml | 2 +- api/client-server/registration.yaml | 12 ++++++------ api/client-server/third_party_membership.yaml | 2 +- api/identity/associations.yaml | 2 +- api/identity/email_associations.yaml | 2 +- api/identity/invitation_signing.yaml | 2 +- api/identity/lookup.yaml | 2 +- api/identity/phone_associations.yaml | 2 +- api/identity/ping.yaml | 2 +- api/identity/pubkey.yaml | 2 +- api/identity/store_invite.yaml | 2 +- .../{identity_server.rst => identity_service.rst} | 0 .../newsfragments/.gitignore | 0 .../pyproject.toml | 2 +- meta/documentation_style.rst | 4 ++++ meta/releasing_a_spec.md | 2 +- scripts/gendoc.py | 2 +- scripts/templating/matrix_templates/sections.py | 4 ++-- scripts/templating/matrix_templates/units.py | 2 +- ...ntity_server_api.rst => identity_service_api.rst} | 8 ++++---- specification/modules/third_party_invites.rst | 4 ++-- specification/server_server_api.rst | 8 ++++---- specification/targets.yaml | 4 ++-- 24 files changed, 40 insertions(+), 36 deletions(-) rename changelogs/{identity_server.rst => identity_service.rst} (100%) rename changelogs/{identity_server => identity_service}/newsfragments/.gitignore (100%) rename changelogs/{identity_server => identity_service}/pyproject.toml (95%) rename specification/{identity_server_api.rst => identity_service_api.rst} (97%) diff --git a/api/client-server/administrative_contact.yaml b/api/client-server/administrative_contact.yaml index 8079e49c..98e997f2 100644 --- a/api/client-server/administrative_contact.yaml +++ b/api/client-server/administrative_contact.yaml @@ -187,7 +187,7 @@ paths: post: summary: Begins the validation process for an email address for association with the user's account. description: |- - Proxies the identity server API ``validate/email/requestToken``, but + Proxies the Identity Service API ``validate/email/requestToken``, but first checks that the given email address is **not** already associated with an account on this homeserver. This API should be used to request validation tokens when adding an email address to an account. This API's @@ -241,7 +241,7 @@ paths: post: summary: Begins the validation process for a phone number for association with the user's account. description: |- - Proxies the identity server API ``validate/msisdn/requestToken``, but + Proxies the Identity Service API ``validate/msisdn/requestToken``, but first checks that the given phone number is **not** already associated with an account on this homeserver. This API should be used to request validation tokens when adding a phone number to an account. This API's diff --git a/api/client-server/create_room.yaml b/api/client-server/create_room.yaml index 29eedb8e..d361d973 100644 --- a/api/client-server/create_room.yaml +++ b/api/client-server/create_room.yaml @@ -141,7 +141,7 @@ paths: description: The hostname+port of the identity server which should be used for third party identifier lookups. medium: type: string - # TODO: Link to identity server spec when it eixsts + # TODO: Link to Identity Service spec when it eixsts description: The kind of address being passed in the address field, for example ``email``. address: type: string diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml index f3a21aab..e2d35d2c 100644 --- a/api/client-server/registration.yaml +++ b/api/client-server/registration.yaml @@ -204,9 +204,9 @@ paths: post: summary: Begins the validation process for an email to be used during registration. description: |- - Proxies the identity server API ``validate/email/requestToken``, but + Proxies the Identity Service API ``validate/email/requestToken``, but first checks that the given email address is not already associated - with an account on this homeserver. See the identity server API for + with an account on this homeserver. See the Identity Service API for further information. operationId: requestTokenToRegisterEmail parameters: @@ -264,9 +264,9 @@ paths: post: summary: Requests a validation token be sent to the given phone number for the purpose of registering an account description: |- - Proxies the identity server API ``validate/msisdn/requestToken``, but + Proxies the Identity Service API ``validate/msisdn/requestToken``, but first checks that the given phone number is not already associated - with an account on this homeserver. See the identity server API for + with an account on this homeserver. See the Identity Service API for further information. operationId: requestTokenToRegisterMSISDN parameters: @@ -373,7 +373,7 @@ paths: post: summary: Requests a validation token be sent to the given email address for the purpose of resetting a user's password description: |- - Proxies the identity server API ``validate/email/requestToken``, but + Proxies the Identity Service API ``validate/email/requestToken``, but first checks that the given email address **is** associated with an account on this homeserver. This API should be used to request validation tokens when authenticating for the @@ -435,7 +435,7 @@ paths: post: summary: Requests a validation token be sent to the given phone number for the purpose of resetting a user's password. description: |- - Proxies the identity server API ``validate/msisdn/requestToken``, but + Proxies the Identity Service API ``validate/msisdn/requestToken``, but first checks that the given phone number **is** associated with an account on this homeserver. This API should be used to request validation tokens when authenticating for the diff --git a/api/client-server/third_party_membership.yaml b/api/client-server/third_party_membership.yaml index 7921da0b..077e1f6a 100644 --- a/api/client-server/third_party_membership.yaml +++ b/api/client-server/third_party_membership.yaml @@ -101,7 +101,7 @@ paths: description: The hostname+port of the identity server which should be used for third party identifier lookups. medium: type: string - # TODO: Link to identity server spec when it eixsts + # TODO: Link to Identity Service spec when it eixsts description: The kind of address being passed in the address field, for example ``email``. address: type: string diff --git a/api/identity/associations.yaml b/api/identity/associations.yaml index a500b87d..edd43f5d 100644 --- a/api/identity/associations.yaml +++ b/api/identity/associations.yaml @@ -13,7 +13,7 @@ # limitations under the License. swagger: '2.0' info: - title: "Matrix Identity Server Establishing Associations API" + title: "Matrix Identity Service Establishing Associations API" version: "1.0.0" host: localhost:8090 schemes: diff --git a/api/identity/email_associations.yaml b/api/identity/email_associations.yaml index 92534461..19faf29a 100644 --- a/api/identity/email_associations.yaml +++ b/api/identity/email_associations.yaml @@ -13,7 +13,7 @@ # limitations under the License. swagger: '2.0' info: - title: "Matrix Identity Server Email Associations API" + title: "Matrix Identity Service Email Associations API" version: "1.0.0" host: localhost:8090 schemes: diff --git a/api/identity/invitation_signing.yaml b/api/identity/invitation_signing.yaml index 8950be29..4e10e2b5 100644 --- a/api/identity/invitation_signing.yaml +++ b/api/identity/invitation_signing.yaml @@ -13,7 +13,7 @@ # limitations under the License. swagger: '2.0' info: - title: "Matrix Identity Server Ephemeral Invitation Signing API" + title: "Matrix Identity Service Ephemeral Invitation Signing API" version: "1.0.0" host: localhost:8090 schemes: diff --git a/api/identity/lookup.yaml b/api/identity/lookup.yaml index ba814d5f..fd50f94b 100644 --- a/api/identity/lookup.yaml +++ b/api/identity/lookup.yaml @@ -16,7 +16,7 @@ # limitations under the License. swagger: '2.0' info: - title: "Matrix Identity Server Lookup API" + title: "Matrix Identity Service Lookup API" version: "1.0.0" host: localhost:8090 schemes: diff --git a/api/identity/phone_associations.yaml b/api/identity/phone_associations.yaml index 558046e1..a327ab6f 100644 --- a/api/identity/phone_associations.yaml +++ b/api/identity/phone_associations.yaml @@ -13,7 +13,7 @@ # limitations under the License. swagger: '2.0' info: - title: "Matrix Identity Server Phone Number Associations API" + title: "Matrix Identity Service Phone Number Associations API" version: "1.0.0" host: localhost:8090 schemes: diff --git a/api/identity/ping.yaml b/api/identity/ping.yaml index b2317cc9..05e12a87 100644 --- a/api/identity/ping.yaml +++ b/api/identity/ping.yaml @@ -15,7 +15,7 @@ swagger: "2.0" info: - title: "Matrix Identity Server Ping API" + title: "Matrix Identity Service Ping API" version: "1.0.0" host: localhost:8090 schemes: diff --git a/api/identity/pubkey.yaml b/api/identity/pubkey.yaml index 92bdace6..e657c61c 100644 --- a/api/identity/pubkey.yaml +++ b/api/identity/pubkey.yaml @@ -13,7 +13,7 @@ # limitations under the License. swagger: '2.0' info: - title: "Matrix Identity Server Public Key API" + title: "Matrix Identity Service Public Key API" version: "1.0.0" host: localhost:8090 schemes: diff --git a/api/identity/store_invite.yaml b/api/identity/store_invite.yaml index b1f9d802..89d437a4 100644 --- a/api/identity/store_invite.yaml +++ b/api/identity/store_invite.yaml @@ -13,7 +13,7 @@ # limitations under the License. swagger: '2.0' info: - title: "Matrix Identity Server Store Invitations API" + title: "Matrix Identity Service Store Invitations API" version: "1.0.0" host: localhost:8090 schemes: diff --git a/changelogs/identity_server.rst b/changelogs/identity_service.rst similarity index 100% rename from changelogs/identity_server.rst rename to changelogs/identity_service.rst diff --git a/changelogs/identity_server/newsfragments/.gitignore b/changelogs/identity_service/newsfragments/.gitignore similarity index 100% rename from changelogs/identity_server/newsfragments/.gitignore rename to changelogs/identity_service/newsfragments/.gitignore diff --git a/changelogs/identity_server/pyproject.toml b/changelogs/identity_service/pyproject.toml similarity index 95% rename from changelogs/identity_server/pyproject.toml rename to changelogs/identity_service/pyproject.toml index b5b8877b..a7fe582d 100644 --- a/changelogs/identity_server/pyproject.toml +++ b/changelogs/identity_service/pyproject.toml @@ -1,5 +1,5 @@ [tool.towncrier] - filename = "../identity_server.rst" + filename = "../identity_service.rst" directory = "newsfragments" issue_format = "`#{issue} `_" title_format = "{version}" diff --git a/meta/documentation_style.rst b/meta/documentation_style.rst index 2f6c9b16..e59ad229 100644 --- a/meta/documentation_style.rst +++ b/meta/documentation_style.rst @@ -71,6 +71,10 @@ Prefer British English (colour, -ise) to American English. The word "homeserver" is spelt thus (rather than "home server", "Homeserver", or (argh) "Home Server"). However, an identity server is two words. +An "identity server" (spelt thus) implements the Identity Service API (also spelt +thus). However, "Application Services" (spelt thus) implement the Application Service +API. Application Services should not be called "appservices" in documentation. + .. Rationale: "homeserver" distinguishes from a "home server" which is a server you have at home. "identity server" is clear, whereas "identityserver" is horrible. diff --git a/meta/releasing_a_spec.md b/meta/releasing_a_spec.md index cbcb03d9..2d9cd34e 100644 --- a/meta/releasing_a_spec.md +++ b/meta/releasing_a_spec.md @@ -1,7 +1,7 @@ # How to release a specification There are several specifications that belong to matrix, such as the client-server -specification, server-server specification, and identity server specification. Each +specification, server-server specification, and identity service specification. Each of these gets released independently of each other with their own version numbers. Once a specification is ready for release, a branch should be created to track the diff --git a/scripts/gendoc.py b/scripts/gendoc.py index 91b58849..8310ad58 100755 --- a/scripts/gendoc.py +++ b/scripts/gendoc.py @@ -527,7 +527,7 @@ if __name__ == '__main__': ) parser.add_argument( "--identity_release", "-i", action="store", default="unstable", - help="The identity server release tag to generate, e.g. r1.2" + help="The identity service release tag to generate, e.g. r1.2" ) parser.add_argument( "--list_targets", action="store_true", diff --git a/scripts/templating/matrix_templates/sections.py b/scripts/templating/matrix_templates/sections.py index 33317e0c..185970c9 100644 --- a/scripts/templating/matrix_templates/sections.py +++ b/scripts/templating/matrix_templates/sections.py @@ -37,9 +37,9 @@ class MatrixSections(Sections): changelogs = self.units.get("changelogs") return changelogs["push_gateway"] - def render_identity_server_changelog(self): + def render_identity_service_changelog(self): changelogs = self.units.get("changelogs") - return changelogs["identity_server"] + return changelogs["identity_service"] def render_server_server_changelog(self): changelogs = self.units.get("changelogs") diff --git a/scripts/templating/matrix_templates/units.py b/scripts/templating/matrix_templates/units.py index 48a11c7f..11a9d441 100644 --- a/scripts/templating/matrix_templates/units.py +++ b/scripts/templating/matrix_templates/units.py @@ -773,7 +773,7 @@ class MatrixUnits(Units): as_ver, "Privileged server plugins", ), TypeTableRow( - "`Identity Server API `_", + "`Identity Service API `_", "unstable", "Mapping of third party IDs to Matrix IDs", ), TypeTableRow( diff --git a/specification/identity_server_api.rst b/specification/identity_service_api.rst similarity index 97% rename from specification/identity_server_api.rst rename to specification/identity_service_api.rst index e236fe0b..2980797f 100644 --- a/specification/identity_server_api.rst +++ b/specification/identity_service_api.rst @@ -15,7 +15,7 @@ .. See the License for the specific language governing permissions and .. limitations under the License. -Identity Server API +Identity Service API ==================== {{unstable_warning_block_IDENTITY_RELEASE_LABEL}} @@ -35,14 +35,14 @@ Changelog --------- .. topic:: Version: %IDENTITY_RELEASE_LABEL% -{{identity_server_changelog}} +{{identity_service_changelog}} This version of the specification is generated from `matrix-doc `_ as of Git commit `{{git_version}} `_. For the full historical changelog, see -https://github.com/matrix-org/matrix-doc/blob/master/changelogs/identity_server.rst +https://github.com/matrix-org/matrix-doc/blob/master/changelogs/identity_service.rst Other versions of this specification @@ -50,7 +50,7 @@ Other versions of this specification The following other versions are also available, in reverse chronological order: -- `HEAD `_: Includes all changes since the latest versioned release. +- `HEAD `_: Includes all changes since the latest versioned release. General principles ------------------ diff --git a/specification/modules/third_party_invites.rst b/specification/modules/third_party_invites.rst index 700f4cdb..9a939143 100644 --- a/specification/modules/third_party_invites.rst +++ b/specification/modules/third_party_invites.rst @@ -215,7 +215,7 @@ H1 MUST verify the request from H3 to ensure the ``signed`` property is correct as well as the ``key_validity_url`` as still being valid. This is done by making a request to the `identity server /isvalid`_ endpoint, using the provided URL rather than constructing a new one. The query string and response for the provided -URL must match the identity server specification. +URL must match the identity service specification. The reason that no other homeserver may reject the event based on checking ``key_validity_url`` is that we must ensure event acceptance is deterministic. @@ -254,4 +254,4 @@ these is left to the implementer's discretion. -.. _`identity server /isvalid`: ../identity_server/unstable.html#get-matrix-identity-api-v1-pubkey-isvalid +.. _`identity server /isvalid`: ../identity_service/unstable.html#get-matrix-identity-api-v1-pubkey-isvalid diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index 19181514..36d7d5d4 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -845,7 +845,7 @@ ID to invite, they can do so using a third-party identifier (e.g. an e-mail or a phone number). This identifier and its bindings to Matrix IDs are verified by an identity server -implementing the `identity server API`_. +implementing the `Identity Service API`_. Cases where an association exists for a third-party identifier ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -866,7 +866,7 @@ request. When a third-party identifier with pending invites gets bound to a Matrix ID, the identity server will send a POST request to the ID's homeserver as described -in the `Invitation Storage`_ section of the identity server API. +in the `Invitation Storage`_ section of the Identity Service API. The following process applies for each invite sent by the identity server: @@ -1192,8 +1192,8 @@ Example code .. |/query/directory| replace:: ``/query/directory`` .. _/query/directory: #get-matrix-federation-v1-query-directory -.. _`Invitation storage`: ../identity_server/%IDENTITY_RELEASE_LABEL%.html#invitation-storage -.. _`identity server API`: ../identity_server/%IDENTITY_RELEASE_LABEL%.html +.. _`Invitation storage`: ../identity_service/%IDENTITY_RELEASE_LABEL%.html#invitation-storage +.. _`Identity Service API`: ../identity_service/%IDENTITY_RELEASE_LABEL%.html .. _`Client-Server API`: ../client_server/%CLIENT_RELEASE_LABEL%.html .. _`Inviting to a room`: #inviting-to-a-room .. _`Canonical JSON`: ../appendices.html#canonical-json diff --git a/specification/targets.yaml b/specification/targets.yaml index bdf0179f..93e1b8a6 100644 --- a/specification/targets.yaml +++ b/specification/targets.yaml @@ -18,9 +18,9 @@ targets: files: - server_server_api.rst version_label: "%SERVER_RELEASE_LABEL%" - identity_server: + identity_service: files: - - identity_server_api.rst + - identity_service_api.rst version_label: "%IDENTITY_RELEASE_LABEL%" push_gateway: files: