* Introduction::           What is the Fediverse?

* API Reference::          Description of the library interface.

@detailmenu

--- The Detailed Node Listing ---

API Reference

* ActivityStreams API::    Encoding and Decoding Activities.

* Webfinger API::          Finding resource locations.

@end detailmenu

The Fediverse is a collection of applications and servers that provide a social

media platform and similar services.  They individually work as a platform,

with users (identities) and services and collectivelly form a bigger social

network, the Fedivere, by the use of different federating protocols.  Some

of them are implemented in this library.

If you are new to the concept of the Fediverse, you should try out one of the

great servers that provide service for Mastodon (the most well-known server),

Pleroma (a micro-blogging platform), Peertube (a video sharing platform), and

many more!  With one account on one of these platforms, you can interact with

any account on any of these other platforms.  Imagine commenting a Peertube

video from Mastodon and sharing it with a friend on Pleroma :)

@node ActivityStreams API

@section ActivityStreams API

@node Webfinger API

@section Webfinger API

Webfinger is a protocol that allows you to query resource location at a

well-known end-point.  The protocol is described in detail in

@uref{RFC 7033, https://tools.ietf.org/html/rfc7033}.

This library provides a small interface to use this protocol in the

@code{(webfinger webfinger)} module.

First of all, webfinger answers are in the form of a @dfn{JRD} record, meaning

JSON Resource Descriptor.  This record is encoded in the @code{<jrd-record>}

data type:

@deffn {Datatype} <jrd-record>

@table @asis

@item @code{subject}

The resource that was requested and for which the answer is given.  This is

a URI, as a string.

@item @code{aliases}

A list of zero or more URI as strings, that identify the same entity.

@item @code{properties}

A list of key-value pairs (an alist) whose keys and values are strings.  This

represents a set of properties on the subject that the webfinger server wants

to give you.

@item @code{links}

A list of links that correspond to the location of the requested identity.  These

links are objects of type @code{<link-record>}.

@end table

@end deffn

@deffn {Datatype} <link-record>

@table @asis

@item @code{rel}

A string that is either a URI or a registered relation type, as defined at

@url{http://www.iana.org/assignments/link-relations/}.

@item @code{type}

A string that represents the MIME/Type of the content accessible through the

link.

@item @code{href}

A string that represents the URI at which you can find of the requested

resource.

@item @code{titles}

An association list where keys are strings that represent a language name and

value represents the title for the content of the link in that language.

@item @code{properties}

A list of key-value pairs (an alist) whose keys and values are strings.  This

represents a set of properties on the link that the webfinger server wants

to give you.

@end table

@end deffn

The library provides two procedures to retrieve data from a webfinger server.

A low-level procedure that can query anything and a higher-level procedure to

specifically query actor objects to a Fediverse server.

@deffn {Scheme Procedure} webfinger-query @var{server} @var{resource} @

  [@var{rel}]

Queries a webfinger @var{server} for @var{resource}, which must be a URI,

represented as a string.  Returns a @code{jrd-record} object.

@end deffn

@deffn {Scheme Procedure} find-actor-object @var{user} @var{server}

Queries a webfinger @var{server} for the actor object of @@@var{user}@@@var{server}.

Note that @var{server} should be a string that represents the server name, but

has no scheme.  The procedure returns a string that corresponds to the best

link returned by the webfinger server (determined by the type when available).

This queries the resource ``acct:@var{user}@@@var{server}'' to the server.

@end deffn