diff options
Diffstat (limited to 'docs/api')
| -rw-r--r-- | docs/api/authentication.md | 19 | ||||
| -rw-r--r-- | docs/api/channels-messages.md | 16 | ||||
| -rw-r--r-- | docs/api/initial-setup.md | 4 | ||||
| -rw-r--r-- | docs/api/invitations.md | 4 |
4 files changed, 41 insertions, 2 deletions
diff --git a/docs/api/authentication.md b/docs/api/authentication.md index 7e05443..135e91b 100644 --- a/docs/api/authentication.md +++ b/docs/api/authentication.md @@ -13,6 +13,23 @@ stateDiagram-v2 Authentication associates each authenticated request with a login. +To create logins, see [initial setup](./initial-setup.md) and [invitations](./invitations.md). + + +## Names + +<!-- This prose is duplicated in channels-messages.md. If you change it here, consider changing it there, too. --> +The service handles login names using two separate forms. + +The first form is as given in the request used to create the login. This form of the login name is used throughout the API, and the service will preserve the name as entered (other than applying normalization), so that users' preferences around capitalization and accent marks are preserved. + +The second form is a "canonical" form, used internally by the service to control uniqueness and match names to logins. The canonical form is both case-folded and normalized. + +The canonical form is not available to API clients, but its use has practical consequences: + +* Names that differ only by case or only by code point sequence are treated as the same name. If the name is in use, changing the capitalization or changing the sequence of combining marks will not allow the creation of a second "identical" login. +* The login API accepts any name that canonicalizes to the form stored in the database, making login names effectively case-insensitive. + ## Identity tokens @@ -32,8 +49,6 @@ Unless the endpoint's documentation says otherwise, all endpoints require authen Authenticates the user using their login name and password. The login must exist before calling this endpoint. -To create logins, see [initial setup](./initial-setup.md) and [invitations](./invitations.md). - **This endpoint does not require an `identity` cookie.** ### Request diff --git a/docs/api/channels-messages.md b/docs/api/channels-messages.md index 1ff037d..9ef4e66 100644 --- a/docs/api/channels-messages.md +++ b/docs/api/channels-messages.md @@ -27,6 +27,18 @@ Messages allow logins to communicate with one another. Channels are the conversa Every channel has a unique name, chosen when the channel is created. +## Names + +<!-- This prose is duplicated in authentication.md. If you change it here, consider changing it there, too. --> +The service handles channel names using two separate forms. + +The first form is as given in the request used to create the channel. This form of the channel name is used throughout the API, and the service will preserve the name as entered (other than applying normalization), so that users' preferences around capitalization and accent marks are preserved. + +The second form is a "canonical" form, used internally by the service to control uniqueness and match names to channels. The canonical form is both case-folded and normalized. + +The canonical form is not available to API clients, but its use has practical consequences. Names that differ only by case or only by code point sequence are treated as the same name. If the name is in use, changing the capitalization or changing the sequence of combining marks will not allow the creation of a second "identical" channel. + + ## Expiry and purging Both channels and messages expire after a time. Messages expire 90 days after being sent. Channels expire 90 days after the last message sent to them, or after creation if no messages are sent in that time. @@ -70,6 +82,8 @@ The response will have the following fields: | `id` | string | A unique identifier for the channel. This can be used to associate the channel with events, or to make API calls targeting the channel. | | `name` | string | The channel's name. | +The returned name may not be identical to the name requested, as the name will be converted to [normalization form C](http://www.unicode.org/reports/tr15/) automatically. The returned name will include this normalization; the service will use the normalized name elsewhere, and does not store the originally requested name. + When completed, the service will emit a [channel created](events.md#channel-created) event with the channel's ID. ### Duplicate channel name @@ -125,6 +139,8 @@ The response will have the following fields: | `id` | string | A unique identifier for the message. This can be used to associate the message with events, or to make API calls targeting the message. | | `body` | string | The message's body. | +The returned message body may not be identical to the body as sent, as the body will be converted to [normalization form C](http://www.unicode.org/reports/tr15/) automatically. The returned body will include this normalization; the service will use the normalized body elsewhere, and does not store the originally submitted body. + When completed, the service will emit a [message sent](events.md#message-sent) event with the message's ID. ### Invalid channel ID diff --git a/docs/api/initial-setup.md b/docs/api/initial-setup.md index 3c5a8a6..306d798 100644 --- a/docs/api/initial-setup.md +++ b/docs/api/initial-setup.md @@ -71,6 +71,10 @@ The response will include the following fields: | `id` | string | A unique identifier for the newly-created login. This can be used to associate the login with other events, or to make API calls targeting the login. | | `name` | string | The login's name. | +The returned name may not be identical to the name requested, as the name will be converted to [normalization form C](http://www.unicode.org/reports/tr15/) automatically. The returned name will include this normalization; the service will use the normalized name elsewhere, and does not store the originally requested name. + +The provided password will also be converted to normalization form C. However, the normalized password is not returned to the client. + The response will include a `Set-Cookie` header for the `identity` cookie, providing the client with a newly-minted identity token associated with the initial login created for this request. See the [authentication](./authentication) section for details on how this cookie may be used. The cookie will expire if it is not used regularly. diff --git a/docs/api/invitations.md b/docs/api/invitations.md index d3431d7..ddbef8a 100644 --- a/docs/api/invitations.md +++ b/docs/api/invitations.md @@ -150,6 +150,10 @@ The response will include the following fields: | `id` | string | A unique identifier for the newly-created login. This can be used to associate the login with other events, or to make API calls targeting the login. | | `name` | string | The login's name. | +The returned name may not be identical to the name requested, as the name will be converted to [normalization form C](http://www.unicode.org/reports/tr15/) automatically. The returned name will include this normalization; the service will use the normalized name elsewhere, and does not store the originally requested name. + +The provided password will also be converted to normalization form C. However, the normalized password is not returned to the client. + The response will include a `Set-Cookie` header for the `identity` cookie, providing the client with a newly-minted identity token associated with the login created for this request. See the [authentication](./authentication.md) section for details on how this cookie may be used. The cookie will expire if it is not used regularly. |