/solace/templates/api/help.html
HTML | 106 lines | 106 code | 0 blank | 0 comment | 0 complexity | a918f48d377742873ad6935b7463f090 MD5 | raw file
Possible License(s): BSD-3-Clause
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 %}