source: gnome/platform/rest.xml@ 50eb39e

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../../general.ent">
  %general-entities;

  <!ENTITY rest-download-http "&gnome-download-http;/rest/0.9/rest-&rest-version;.tar.xz">
  <!ENTITY rest-download-ftp  " ">
  <!ENTITY rest-md5sum        "b997b83232be3814a1b78530c5700df9">
  <!ENTITY rest-size          "72 KB">
  <!ENTITY rest-buildsize     "3.2 MB (with tests)">
  <!ENTITY rest-time          "0.1 SBU (with tests)">
]>

<sect1 id="rest" xreflabel="rest-&rest-version;">
  <?dbhtml filename="rest.html"?>


  <title>rest-&rest-version;</title>

  <indexterm zone="rest">
    <primary sortas="a-rest">rest</primary>
  </indexterm>

  <sect2 role="package">
    <title>Introduction to rest</title>

    <para>
      The <application>rest</application> package contains a library
      that was designed to make it easier to access web services that
      claim to be "RESTful". It includes convenience wrappers for
      libsoup and libxml to make remote usage of the RESTful API easier.
    </para>

    &lfs122_checked;

    <bridgehead renderas="sect3">Package Information</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>
          Download (HTTP): <ulink url="&rest-download-http;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download (FTP): <ulink url="&rest-download-ftp;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download MD5 sum: &rest-md5sum;
        </para>
      </listitem>
      <listitem>
        <para>
          Download size: &rest-size;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated disk space required: &rest-buildsize;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated build time: &rest-time;
        </para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">rest Dependencies</bridgehead>

    <bridgehead renderas="sect4">Required</bridgehead>
    <para role="required">
      <xref linkend="json-glib"/>,
      <xref linkend="libsoup3"/>, and
      <xref linkend="make-ca"/>
    </para>

    <bridgehead renderas="sect4">Recommended</bridgehead>
    <para role="recommended">
      &gobject-introspection;
    </para>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional">
      <xref linkend="gi-docgen"/>,
      <xref linkend="libadwaita1"/> and
      <xref linkend="gtksourceview5"/> (to build the demo), and
      <xref linkend="vala"/>
    </para>

    &test-use-internet;

  </sect2>

  <sect2 role="installation">
    <title>Installation of rest</title>

    <para>
      Install <application>rest</application> by running the following
      commands:
    </para>

<screen><userinput>mkdir build &amp;&amp;
cd    build &amp;&amp;

meson setup --prefix=/usr       \
            --buildtype=release \
            -D examples=false   \
            -D gtk_doc=false    \
            ..                  &amp;&amp;
ninja</userinput></screen>

    <para>
      If you have <xref linkend='gi-docgen'/> installed and wish to build
      the API documentation for this package, issue:
    </para>

<screen role='nodump'><userinput>sed "/output/s/librest-1.0/rest-&rest-version;/" -i ../docs/meson.build &amp;&amp;
meson configure -D gtk_doc=true                                &amp;&amp;
ninja</userinput></screen>

    <para>
      To test the results, issue: <command>ninja test</command>.
    </para>

    <para>
      Now, as the <systemitem class="username">root</systemitem> user:
    </para>

<screen role="root"><userinput>ninja install</userinput></screen>

  </sect2>

  <sect2 role="commands">
    <title>Command Explanations</title>

    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
    href="../../xincludes/meson-buildtype-release.xml"/>

    <para>
      <parameter>-D gtk_doc=false</parameter>: &gi-doc-disable;
    </para>

    <para>
      <parameter>-D examples=false</parameter>: Remove this option if
      <xref linkend="libadwaita1"/> and <xref linkend="gtksourceview5"/> are
      installed and you wish to build the demonstration application provided
      by this package.
    </para>

    <para>
      <option>-D vapi=true</option>: Use this switch if <xref linkend="vala"/>
      is installed and you wish to build the Vala bindings provided by this
      package.
    </para>
  </sect2>

  <sect2 role="content">
    <title>Contents</title>

    <segmentedlist>
      <segtitle>Installed Programs</segtitle>
      <segtitle>Installed Libraries</segtitle>
      <segtitle>Installed Directories</segtitle>

      <seglistitem>
        <seg>
          librest-demo (optional)
        </seg>
        <seg>
          librest-1.0.so and librest-extras-1.0.so
        </seg>
        <seg>
          /usr/include/rest-1.0 and
          /usr/share/gtk-doc/html/rest-1.0
        </seg>
      </seglistitem>
    </segmentedlist>

    <variablelist>
      <bridgehead renderas="sect3">Short Descriptions</bridgehead>
      <?dbfo list-presentation="list"?>
      <?dbhtml list-presentation="table"?>

      <varlistentry id="librest-demo">
        <term><command>librest-demo</command></term>
        <listitem>
          <para>
            provides an example of how to use the RESTful Web API Query
            functions
          </para>
          <indexterm zone="rest librest-demo">
            <primary sortas="b-librest-demo">librest-demo</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="librest-1.0">
        <term><filename class="libraryfile">librest-1.0.so</filename></term>
        <listitem>
          <para>
            contains the RESTful Web API Query functions
          </para>
          <indexterm zone="rest librest-1.0">
            <primary sortas="c-librest-1.0">librest-1.0.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="librest-extras-1.0">
        <term><filename class="libraryfile">librest-extras-1.0.so</filename></term>
        <listitem>
          <para>
            contains extra RESTful Web API Query functions
          </para>
          <indexterm zone="rest librest-extras-1.0">
            <primary sortas="c-librest-extras-1.0">librest-extras-1.0.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>