HTTP Link header: use GOOPS and document it

1 files changed, 66 insertions, 0 deletions

diff --git a/doc/disfluid.texi b/doc/disfluid.texi
index 011f3f9..be32b85 100644
--- a/doc/disfluid.texi
+++ b/doc/disfluid.texi
@@ -71,6 +71,7 @@ A PDF version of this manual is available at
 * Client manifest::
 * The Json Web Token::
 * Caching on server side::
+* The HTTP Link header::
 * Content negociation::
 * Running an Identity Provider::
 * Running a Resource Server::
@@ -1401,6 +1402,71 @@ This parameters sets the cache directory. By default, it is
 @emph{XDG_CACHE_HOME}.
 @end deffn
 
+@node The HTTP Link header
+@chapter The HTTP Link header
+The HTTP Link header lets you attach metadata about a resource,
+directly in the HTTP protocol. It is used to link resources to their
+auxiliary resources, for instance.
+
+The following API is defined in @emph{(webid-oidc http-link)}:
+
+@deftp {Class} <link> @var{target-iri} @var{relation-type} @var{target-attributes}
+The link refers to the @var{target-iri} that is being linked to the
+requested resource, with a given @var{relation-type} (a string), and
+optional additional @var{target-attributes}.
+
+When constructing a <link>, you should use the
+@code{#:@var{target-iri}}, @code{#:@var{relation-type}} and
+@code{#:@var{target-attributes}} keyword arguments
+(@code{#:@var{target-attributes}} defaults to the empty list) to
+initialize the link. For convenience, the @code{#:@var{anchor}},
+@code{#:@var{hreflang}}, @code{#:@var{media}}, @code{#:@var{title}},
+@code{#:@var{title*}} and @code{#:@var{type}} keyword arguments can be
+passed to add well-known target attributes.
+@end deftp
+
+@deftp {Class} <target-attribute> @var{key} @var{value}
+If you wish to add new extension target attributes, you can create an
+ad-hoc target attribute with @var{key} and @var{value} (initialized as
+@code{#:@var{key}} and @code{#:@var{value}} constructor keyword
+arguments).
+@end deftp
+
+@deffn {Generic} target-iri @var{link}
+@deffnx {Generic} relation-type @var{link}
+@deffnx {Generic} target-attributes @var{link}
+Getters for the @code{<link>} class.
+@end deffn
+
+@deffn {Generic} key @var{target-attribute}
+@deffnx {Generic} value @var{target-attribute}
+Getters for the @code{<target-attribute>} class.
+@end deffn
+
+@deffn {Generic} target-attribute @var{link} @var{key}
+Return the value of the first target attributet with @var{key}.
+@end deffn
+
+@deffn {Generic} anchor @var{link}
+@deffnx {Generic} hreflang @var{link}
+@deffnx {Generic} media @var{link}
+@deffnx {Generic} title @var{link}
+@deffnx {Generic} title* @var{link}
+@deffnx {Generic} type @var{link}
+Convenience attribute lookup functions. @code{anchor} returns an URI
+referencce, the others return a string.
+@end deffn
+
+@deffn {function} declare-link-header!
+Declare functions to parse, validate and print HTTP Link headers with
+the Guile web request / response API.
+@end deffn
+
+@deffn {function} request-links @var{request}
+@deffnx {function} response-links @var{response}
+Return the list of links in @var{request} or @var{response}.
+@end deffn
+
 @node Content negociation
 @chapter Content negociation
 There are a number of different available syntaxes for RDF, some being