/solace/templates/api/help.html

  1{% extends 'layout.html' %}
  2{% set page_title = 'API Help' %}
  3{% block body %}
  4  <h1>{{ page_title }}</h1>
  5  <div class="apihelp">
  6    <p>
  7      Welcome to the Solace API.  Currently this API is limited to read-only
  8      access to Solace.
  9    <h2>API Usage</h2>
 10    <p>
 11      The Solace API is accessed via HTTP on the API URL (the URL of the page
 12      you're looking at right now).  The method you want to access is then
 13      appended to the URL.  For example to use the <code>get_user</code>
 14      method you would open a connection to the following URL:
 15    <pre>{{ request.url }}users/username</pre>
 16    <p>
 17      The format of the data returned can be one of the following:
 18    <ul>
 19      <li>json <small>application/json</small>
 20      <li>xml <small>application/xml</small>
 21      <li>debug <small>text/html</small>
 22    </ul>
 23    <p>
 24      The format is selected based on the <code>Accept</code> HTTP header or
 25      can be provided as URL parameter:
 26    <pre>{{ request.url }}badges/?format=xml</pre>
 27    <p>
 28      The language of the response is selected from the <code>Accept-Language</code>
 29      header or the <code>lang</code> URL parameter:
 30    <pre>{{ request.url }}badges/?lang=de</pre>
 31    <p>
 32      It is strongly recommended to use the HTTP headers instead of the URL
 33      parameters.  The headers allow you to provide multiple values and let
 34      the server pick the ones that are available.
 35    <p>
 36      For debugging you can use your web browser and open the URL with it.  The
 37      default headers of a web browser will return the response in debug HTML
 38      format which shows you the data right in your browser in a human readable
 39      fashion.
 40    <h2>General Rules</h2>
 41    <p>
 42      The API follows REST semantics as closely as possible without causing
 43      too much troubles for server and client.  Make sure to follow the
 44      following rules:
 45    <ul>
 46      <li>If a resource URL is documented with a trailing slash you
 47          <strong>must</strong> connect to it with a trailing slash
 48      <li>For valid requests the server will never return a redirect
 49          you have to handle.
 50      <li>All data returned, except for data that is HTML, is not
 51          preprocessed.  If you intend to embedd it on a webpage make
 52          sure to properly escape the data!
 53      <li>Rendered HTML is only valid in HTML 4 and HTML 5, not in
 54          any version of XHTML!  If you are using XHTML and want to
 55          embedd rendered data you <strong>must</strong> parse it as
 56          HTML and dump into XML.
 57      <li>The encoding used for requests and responses to and from
 58          Solace are always utf-8.
 59      <li>The API responds with HTTP error codes.  Make sure to be able
 60          to handle <strong>every</strong> error code the RFC specifies.
 61    </ul>
 62    <h2>XML Format</h2>
 63    <p>
 64      If you don't want (or can) use the JSON format which is strongly
 65      recommended you can also use our XML representation of the data.
 66    <p>
 67      The following rules apply for the XML format:
 68    <ul>
 69      <li><p>All elements returned from the API belong to the
 70          <code>{{ xmlns }}</code> XML namespace.
 71      <li><p>If an object in JSON has a <code>#type</code> key and the value
 72          starts with <code>solace.</code> the value after <code>solace.</code>
 73          is used as tag:
 74          <pre>{'#type': 'solace.foo', 'bar': 'bar'}</pre>
 75          <p>becomes in XML
 76          <pre>{{ '<foo><bar>baz</bar></foo>'|e }}</pre>
 77      <li><p>Otherwise the object is returned as dict and the type is
 78          stored as attribute:
 79          <pre>{'foo': 'bar', '#type': 'special'}</pre>
 80          <p>becomes in XML
 81          <pre>{{ '<dict type="special"><foo>bar</foo></dict>'|e }}</pre>
 82          <p>If no <code>#type</code> key exists that attribute is missing.
 83      <li><p>List items are wrapped in a <code>list</code> tag:
 84          <pre>[1, 2, {'foo': 'bar'}]</pre>
 85          <p>becomes in XML
 86          <pre>{{ '<list><item>1</item><item>2</item><dict><foo>bar</foo></dict></list>'|e }}</pre>
 87    </ul>
 88    <h2>Methods</h2>
 89    <p>
 90      The following API methods exist:
 91    <ul class="apimethods">
 92    {% for method in methods %}
 93      <li class="method"><h3>{{ method.handler.replace('_', ' ').title() }}</h3>
 94        <div class="inner">
 95          <div class="description">{{ method.doc }}</div>
 96          <dl>
 97            <dt>URL
 98            <dd>{{ method.url|e }}
 99            <dt>Allowed methods
100            <dd>{{ method.valid_methods|join(', ') }}
101          </dl>
102        </div>
103    {% endfor %}
104    </ul>
105  </div>
106{% endblock %}