From df601c07b7d643f1dd8fdc2615e795b3f3ea1b3b Mon Sep 17 00:00:00 2001
From: Vivien Kraus <vivien@planete-kraus.eu>
Date: Fri, 2 Jul 2021 10:47:58 +0200
Subject: Set up content negociation

To add support for new conversion strategies, edit serve.scm and fetch.scm.
---
 doc/webid-oidc.texi | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

(limited to 'doc')

diff --git a/doc/webid-oidc.texi b/doc/webid-oidc.texi
index ba23010..a6852a8 100644
--- a/doc/webid-oidc.texi
+++ b/doc/webid-oidc.texi
@@ -49,6 +49,7 @@ Free Documentation License''
 * Decentralized Authentication on the Web::
 * The Json Web Token::
 * Caching on server side::
+* Content negociation::
 * Running an Identity Provider::
 * Running a Resource Server::
 * Running a client::
@@ -369,6 +370,32 @@ The back-end function, @var{http-get}, defaults to that of
 @emph{(web client)}.
 @end deffn
 
+@node Content negociation
+@chapter Content negociation
+There are a number of different available syntaxes for RDF, some being
+simple and human readable like @emph{turtle}, and others more adapted
+to the JavaScript ecosystem like @emph{json-ld}. To help clients both
+from and outside of the JS ecosystem, the server needs to perform
+@dfn{content negociation}, i.e. convert from one content-type to
+another.
+
+@deffn {function from @code{(webid-oidc serve)}} convert @var{client-accepts} @var{server-name} @var{path} @var{content-type} @var{content}
+Convert the resource representation under @var{path} on
+@var{server-name}, which has a given @var{content-type} and
+@var{content}, to a content-type that the @var{client accepts}.
+
+Return 2 values:
+@enumerate
+@item
+the accepted content-type;
+@item
+the content in the given content-type.
+@end enumerate
+
+Currently, the only conversions are from and to @emph{Turtle} and
+@emph{N-Quads}.
+@end deffn
+
 @node Running an Identity Provider
 @chapter Running an Identity Provider
 
@@ -1302,6 +1329,12 @@ If the resource does not exist, @var{real-etag} is set to
 @code{#f}. In this case, an exception of type @code{&path-not-found}
 is also thrown.
 @end deftp
+
+@deftp {exception type} &not-acceptable @var{client-accepts} @var{path} @var{content-type}
+The client wanted a response with a specific set of
+@var{client-accept}ed content-types, but the real @var{content-type}
+of the resource under @var{path} cannot be converted to one of them.
+@end deftp
 @node GNU Free Documentation License
 @appendix GNU Free Documentation License
 
-- 
cgit v1.2.3