5 <meta name=
"generator" content=
"pandoc">
6 <meta name=
"viewport" content=
"width=device-width, initial-scale=1.0, user-scalable=yes">
7 <title>Shaarli – REST API
</title>
8 <style type=
"text/css">code{white-space: pre;}
</style>
9 <style type=
"text/css">
10 div.sourceCode { overflow-x: auto; }
11 table.sourceCode, tr.sourceCode, td.lineNumbers, td.sourceCode {
12 margin:
0; padding:
0; vertical-align: baseline; border: none; }
13 table.sourceCode { width:
100%; line-height:
100%; }
14 td.lineNumbers { text-align: right; padding-right:
4px; padding-left:
4px; color: #aaaaaa; border-right:
1px solid #aaaaaa; }
15 td.sourceCode { padding-left:
5px; }
16 code
> span.kw { color: #
007020; font-weight: bold; } /* Keyword */
17 code
> span.dt { color: #
902000; } /* DataType */
18 code
> span.dv { color: #
40a070; } /* DecVal */
19 code
> span.bn { color: #
40a070; } /* BaseN */
20 code
> span.fl { color: #
40a070; } /* Float */
21 code
> span.ch { color: #
4070a0; } /* Char */
22 code
> span.st { color: #
4070a0; } /* String */
23 code
> span.co { color: #
60a0b0; font-style: italic; } /* Comment */
24 code
> span.ot { color: #
007020; } /* Other */
25 code
> span.al { color: #ff0000; font-weight: bold; } /* Alert */
26 code
> span.fu { color: #
06287e; } /* Function */
27 code
> span.er { color: #ff0000; font-weight: bold; } /* Error */
28 code
> span.wa { color: #
60a0b0; font-weight: bold; font-style: italic; } /* Warning */
29 code
> span.cn { color: #
880000; } /* Constant */
30 code
> span.sc { color: #
4070a0; } /* SpecialChar */
31 code
> span.vs { color: #
4070a0; } /* VerbatimString */
32 code
> span.ss { color: #bb6688; } /* SpecialString */
33 code
> span.im { } /* Import */
34 code
> span.va { color: #
19177c; } /* Variable */
35 code
> span.cf { color: #
007020; font-weight: bold; } /* ControlFlow */
36 code
> span.op { color: #
666666; } /* Operator */
37 code
> span.bu { } /* BuiltIn */
38 code
> span.ex { } /* Extension */
39 code
> span.pp { color: #bc7a00; } /* Preprocessor */
40 code
> span.at { color: #
7d9029; } /* Attribute */
41 code
> span.do { color: #ba2121; font-style: italic; } /* Documentation */
42 code
> span.an { color: #
60a0b0; font-weight: bold; font-style: italic; } /* Annotation */
43 code
> span.cv { color: #
60a0b0; font-weight: bold; font-style: italic; } /* CommentVar */
44 code
> span.in { color: #
60a0b0; font-weight: bold; font-style: italic; } /* Information */
46 <link rel=
"stylesheet" href=
"github-markdown.css">
48 <script src="//cdnjs.cloudflare.com/ajax/libs/html5shiv/3.7.3/html5shiv-printshiv.min.js"></script>
52 <div id=
"local-sidebar">
54 <li><a href=
"Home.html">Home
</a></li>
57 <li><a href=
"Download-and-Installation.html">Download and Installation
</a></li>
58 <li><a href=
"Upgrade-and-migration.html">Upgrade and migration
</a></li>
59 <li><a href=
"Server-requirements.html">Server requirements
</a></li>
60 <li><a href=
"Server-configuration.html">Server configuration
</a></li>
61 <li><a href=
"Server-security.html">Server security
</a></li>
62 <li><a href=
"Shaarli-configuration.html">Shaarli configuration
</a></li>
63 <li><a href=
"Plugins.html">Plugins
</a></li>
65 <li><a href=
"Docker.html">Docker
</a></li>
66 <li><a href=
"Usage.html">Usage
</a>
68 <li><a href=
"Sharing-button.html">Sharing button
</a> (bookmarklet)
</li>
69 <li><a href=
"Browsing-and-Searching.html">Browsing and Searching
</a></li>
70 <li><a href=
"Firefox-share.html">Firefox share
</a></li>
71 <li><a href=
"RSS-feeds.html">RSS feeds
</a></li>
72 <li><a href=
"REST-API.html">REST API
</a></li>
76 <li><a href=
"Backup,-restore,-import-and-export.html">Backup, restore, import and export
</a></li>
77 <li><a href=
"Copy-an-existing-installation-over-SSH-and-serve-it-locally.html">Copy an existing installation over SSH and serve it locally
</a></li>
78 <li><a href=
"Create-and-serve-multiple-Shaarlis-(farm).html">Create and serve multiple Shaarlis (farm)
</a></li>
79 <li><a href=
"Download-CSS-styles-from-an-OPML-list.html">Download CSS styles from an OPML list
</a></li>
80 <li><a href=
"Datastore-hacks.html">Datastore hacks
</a></li>
82 <li><a href=
"Troubleshooting.html">Troubleshooting
</a></li>
83 <li><a href=
"Development.html">Development
</a>
85 <li><a href=
"GnuPG-signature.html">GnuPG signature
</a></li>
86 <li><a href=
"Coding-guidelines.html">Coding guidelines
</a></li>
87 <li><a href=
"Directory-structure.html">Directory structure
</a></li>
88 <li><a href=
"3rd-party-libraries.html">3rd party libraries
</a></li>
89 <li><a href=
"Plugin-System.html">Plugin System
</a></li>
90 <li><a href=
"Release-Shaarli.html">Release Shaarli
</a></li>
91 <li><a href=
"Versioning-and-Branches.html">Versioning and Branches
</a></li>
92 <li><a href=
"Security.html">Security
</a></li>
93 <li><a href=
"Static-analysis.html">Static analysis
</a></li>
94 <li><a href=
"Theming.html">Theming
</a></li>
95 <li><a href=
"Unit-tests.html">Unit tests
</a></li>
99 <li><a href=
"FAQ.html">FAQ
</a></li>
100 <li><a href=
"Community-&-Related-software.html">Community
& Related software
</a></li>
104 <h1 id=
"rest-api">REST API
</h1>
105 <h2 id=
"usage">Usage
</h2>
106 <p>See the
<a href=
"http://shaarli.github.io/api-documentation/">REST API documentation
</a>.
<a href=
".html"></a></p>
107 <h2 id=
"authentication">Authentication
</h2>
108 <p>All requests to Shaarli's API must include a JWT token to verify their authenticity.
</p>
109 <p>This token has to be included as an HTTP header called
<code>Authentication: Bearer
<jwt token
></code>.
</p>
110 <p>JWT resources :
</p>
112 <li><a href=
"https://jwt.io">jwt.io
</a> (including a list of client per language).
<a href=
".html"></a></li>
113 <li>RFC :
<a href=
"https://tools.ietf.org/html/rfc7519" class=
"uri">https://tools.ietf.org/html/rfc7519
</a></li>
114 <li><a href=
"https://float-middle.com/json-web-tokens-jwt-vs-sessions/" class=
"uri">https://float-middle.com/json-web-tokens-jwt-vs-sessions/
</a></li>
115 <li>HackerNews thread:
<a href=
"https://news.ycombinator.com/item?id=11929267" class=
"uri">https://news.ycombinator.com/item?id=
11929267</a></li>
117 <h3 id=
"shaarli-jwt-token">Shaarli JWT Token
</h3>
118 <p>JWT tokens are composed by three parts, separated by a dot
<code>.
</code> and encoded in base64:
</p>
119 <pre><code>[header].[payload].[signature][](.html)
</code></pre>
120 <h4 id=
"header">Header
</h4>
121 <p>Shaarli only allow one hash algorithm, so the header will always be the same:
</p>
122 <div class=
"sourceCode"><pre class=
"sourceCode json"><code class=
"sourceCode json"><span class=
"fu">{
</span>
123 <span class=
"dt">"typ
"</span><span class=
"fu">:
</span> <span class=
"st">"JWT
"</span><span class=
"fu">,
</span>
124 <span class=
"dt">"alg
"</span><span class=
"fu">:
</span> <span class=
"st">"HS512
"</span>
125 <span class=
"fu">}
</span></code></pre></div>
126 <p>Encoded in base64, it gives:
</p>
127 <pre><code>ewogICAgICAgICJ0eXAiOiAiSldUIiwKICAgICAgICAiYWxnIjogIkhTNTEyIgogICAgfQ==
</code></pre>
128 <h4 id=
"payload">Payload
</h4>
129 <p><strong>Validity duration
</strong></p>
130 <p>To avoid infinite token validity, JWT tokens must include their creation date in UNIX timestamp format (timezone independant - UTC) under the key
<code>iat
</code> (issued at). This token will be accepted during
9 minutes.
</p>
131 <div class=
"sourceCode"><pre class=
"sourceCode json"><code class=
"sourceCode json"><span class=
"fu">{
</span>
132 <span class=
"dt">"iat
"</span><span class=
"fu">:
</span> <span class=
"dv">1468663519</span>
133 <span class=
"fu">}
</span></code></pre></div>
134 <p>See
<a href=
"https://tools.ietf.org/html/rfc7519#section-4.1.6">RFC reference
</a>.
<a href=
".html"></a></p>
135 <h4 id=
"signature">Signature
</h4>
136 <p>The signature authenticate the token validity. It contains the base64 of the header and the body, separated by a dot
<code>.
</code>, hashed in SHA512 with the API secret available in Shaarli administration page.
</p>
137 <p>Signature example with PHP:
</p>
138 <div class=
"sourceCode"><pre class=
"sourceCode php"><code class=
"sourceCode php"><span class=
"kw">$content
</span> =
<span class=
"fu">base64_encode
</span><span class=
"ot">(
</span><span class=
"kw">$header
</span><span class=
"ot">)
</span> .
<span class=
"st">'.
'</span> .
<span class=
"fu">base64_encode
</span><span class=
"ot">(
</span><span class=
"kw">$payload
</span><span class=
"ot">);
</span>
139 <span class=
"kw">$signature
</span> =
<span class=
"fu">hash_hmac
</span><span class=
"ot">(
</span><span class=
"st">'sha512
'</span><span class=
"ot">,
</span> <span class=
"kw">$content
</span><span class=
"ot">,
</span> <span class=
"kw">$secret
</span><span class=
"ot">);
</span></code></pre></div>
140 <h3 id=
"complete-example">Complete example
</h3>
141 <h4 id=
"php">PHP
</h4>
142 <div class=
"sourceCode"><pre class=
"sourceCode php"><code class=
"sourceCode php"><span class=
"kw">function
</span> generateToken
<span class=
"ot">(
</span><span class=
"kw">$secret
</span><span class=
"ot">)
</span> {
143 <span class=
"kw">$header
</span> =
<span class=
"fu">base64_encode
</span><span class=
"ot">(
</span><span class=
"st">'{
</span>
144 <span class=
"st"> "typ
":
"JWT
",
</span>
145 <span class=
"st"> "alg
":
"HS512
"</span>
146 <span class=
"st"> }
'</span><span class=
"ot">);
</span>
147 <span class=
"kw">$payload
</span> =
<span class=
"fu">base64_encode
</span><span class=
"ot">(
</span><span class=
"st">'{
</span>
148 <span class=
"st"> "iat
":
'</span>.
<span class=
"fu">time
</span><span class=
"ot">()
</span> .
<span class=
"st">'</span>
149 <span class=
"st"> }
'</span><span class=
"ot">);
</span>
150 <span class=
"kw">$signature
</span> =
<span class=
"fu">hash_hmac
</span><span class=
"ot">(
</span><span class=
"st">'sha512
'</span><span class=
"ot">,
</span> <span class=
"kw">$header
</span> .
<span class=
"st">'.
'</span>.
<span class=
"kw">$payload
</span> <span class=
"ot">,
</span> <span class=
"kw">$secret
</span><span class=
"ot">);
</span>
151 <span class=
"kw">return
</span> <span class=
"kw">$header
</span> .
<span class=
"st">'.
'</span>.
<span class=
"kw">$payload
</span> .
<span class=
"st">'.
'</span>.
<span class=
"kw">$signature
</span><span class=
"ot">;
</span>
154 <span class=
"kw">$secret
</span> =
<span class=
"st">'mysecret
'</span><span class=
"ot">;
</span>
155 <span class=
"kw">$token
</span> = generateToken
<span class=
"ot">(
</span><span class=
"kw">$secret
</span><span class=
"ot">);
</span>
156 <span class=
"fu">echo
</span> <span class=
"kw">$token
</span><span class=
"ot">;
</span></code></pre></div>
158 <p><code>ewogICAgICAgICJ0eXAiOiAiSldUIiwKICAgICAgICAiYWxnIjogIkhTNTEyIgogICAgfQ==.ewogICAgICAgICJpYXQiOiAxNDY4NjY3MDQ3CiAgICB9.1d2c54fa947daf594fdbf7591796195652c8bc63bffad7f6a6db2a41c313f495a542cbfb595acade79e83f3810d709b4251d7b940bbc10b531a6e6134af63a68
</code></p>
160 <div class=
"sourceCode"><pre class=
"sourceCode php"><code class=
"sourceCode php"><span class=
"kw">$options
</span> =
<span class=
"ot">[[](
</span>.html
<span class=
"ot">)
</span>
161 <span class=
"st">'http
'</span> =
> <span class=
"ot">[[](
</span>.html
<span class=
"ot">)
</span>
162 <span class=
"st">'method
'</span> =
> <span class=
"st">'GET
'</span><span class=
"ot">,
</span>
163 <span class=
"st">'jwt
'</span> =
> <span class=
"kw">$token
</span><span class=
"ot">,
</span>
164 <span class=
"ot">],
</span>
165 <span class=
"ot">];
</span>
166 <span class=
"kw">$context
</span> =
<span class=
"fu">stream_context_create
</span><span class=
"ot">(
</span><span class=
"kw">$options
</span><span class=
"ot">);
</span>
167 <span class=
"fu">file_get_contents
</span><span class=
"ot">(
</span><span class=
"kw">$apiEndpoint
</span><span class=
"ot">,
</span> <span class=
"kw">false
</span><span class=
"ot">,
</span> <span class=
"kw">$context
</span><span class=
"ot">);
</span></code></pre></div>