Unverified Commit b8aeaa40 authored by Hong Minhee's avatar Hong Minhee
Browse files

Comprehensive URI Template syntax guide 

Added a new documentation page explaining RFC 6570 URI Template syntax
and its usage throughout Fedify's routing system. The guide covers:

- Different expansion types ({var}, {+var}, {/var}, {?var}, {&var})
- When to use each expansion type
- Common use cases for actors, collections, inbox listeners, and objects
- Common pitfalls like double-encoding with URI identifiers
- Decision guide and troubleshooting tips

Also added cross-references from actor.md, collections.md, inbox.md,
and object.md to help users choose the appropriate expansion syntax
for their identifiers.

Close https://github.com/fedify-dev/fedify/issues/417
parent 4bb3969f

docs/.vitepress/config.mts

+1 −0
Original line number Diff line number Diff line
@@ -70,6 +70,7 @@ const MANUAL = { 
    { text: "Access control", link: "/manual/access-control.md" },

    { text: "WebFinger", link: "/manual/webfinger.md" },

    { text: "NodeInfo", link: "/manual/nodeinfo.md" },

    { text: "URI Template", link: "/manual/uri-template.md" },

    { text: "Pragmatics", link: "/manual/pragmatics.md" },

    { text: "Key–value store", link: "/manual/kv.md" },

    { text: "Message queue", link: "/manual/mq.md" },

docs/manual/actor.md

+7 −0
Original line number Diff line number Diff line
@@ -66,6 +66,13 @@ follows the [URI Template] specification. 
> See the [next section](#decoupling-actor-uris-from-webfinger-usernames)

> for details.



> [!NOTE]

> The URI Template syntax supports different expansion types like `{identifier}`

> (simple expansion) and `{+identifier}` (reserved expansion).  Choosing the

> right expansion type is important to avoid encoding issues.  See the

> [*URI Template* guide](./uri-template.md) for details on when to use

> each type.



[actors]: https://www.w3.org/TR/activitystreams-core/#actors

[activities]: https://www.w3.org/TR/activitystreams-core/#activities

[URI Template]: https://datatracker.ietf.org/doc/html/rfc6570

docs/manual/collections.md

+22 −15
Original line number Diff line number Diff line
@@ -47,6 +47,13 @@ Each actor has its own outbox collection, so the URI pattern of the outbox 
dispatcher should include the actor's `{identifier}`.  The URI pattern syntax

follows the [URI Template] specification.



> [!NOTE]

> The URI Template syntax supports different expansion types like `{identifier}`

> (simple expansion) and `{+identifier}` (reserved expansion).  If your

> identifiers contain URIs or special characters, you may need to use

> `{+identifier}` to avoid double-encoding issues.  See the

> [*URI Template* guide](./uri-template.md) for details.



Since the outbox is a collection of activities, the outbox dispatcher should

return an array of activities.  The following example shows how to construct

an outbox collection:

docs/manual/inbox.md

+7 −0
Original line number Diff line number Diff line
@@ -82,6 +82,13 @@ and a callback function that takes a `Context` object and the activity object. 
Note that the `~InboxListenerSetters.on()` method can be chained to register

multiple inbox listeners for different activity types.



> [!NOTE]

> The URI Template syntax supports different expansion types like `{identifier}`

> (simple expansion) and `{+identifier}` (reserved expansion).  If your

> identifiers contain URIs or special characters, you may need to use

> `{+identifier}` to avoid double-encoding issues.  See the

> [*URI Template* guide](./uri-template.md) for details.



> [!WARNING]

> Activities of any type that are not registered with

> the `~InboxListenerSetters.on()` method are silently ignored.

docs/manual/object.md

+7 −0
Original line number Diff line number Diff line
@@ -53,6 +53,13 @@ an object dispatcher for the `Note` class and 
the `/users/{userId}/notes/{noteId}` path.  This pattern syntax follows

the [URI Template] specification.



> [!NOTE]

> The URI Template syntax supports different expansion types like `{userId}`

> (simple expansion) and `{+userId}` (reserved expansion).  If your

> identifiers contain URIs or special characters, you may need to use

> `{+userId}` to avoid double-encoding issues.  See the

> [*URI Template* guide](./uri-template.md) for details.



[objects]: https://www.w3.org/TR/activitystreams-core/#object

[URI Template]: https://datatracker.ietf.org/doc/html/rfc6570