X-Git-Url: https://git.immae.eu/?a=blobdiff_plain;f=doc%2Fmd%2FREST-API.md;h=01071d8e550775d7836d99a6129ca5871a7a3d27;hb=dfed9b2dd58cfb82a334f4c9433bfce84426cd34;hp=ad4077490d7afd8fb6a85caabaaba03111ca3946;hpb=e62486dd6a76fc77f062b81c861eb3ee807b1682;p=github%2Fshaarli%2FShaarli.git diff --git a/doc/md/REST-API.md b/doc/md/REST-API.md index ad407749..01071d8e 100644 --- a/doc/md/REST-API.md +++ b/doc/md/REST-API.md @@ -1,30 +1,86 @@ -## Usage +# REST API -See the [REST API documentation](http://shaarli.github.io/api-documentation/). +## Server requirements -## Authentication +See the **[REST API documentation](http://shaarli.github.io/api-documentation/)** for a list of available endpoints and parameters. -All requests to Shaarli's API must include a JWT token to verify their authenticity. +Please ensure that your server meets the requirements and is properly [configured](Server-configuration): -This token has to be included as an HTTP header called `Authentication: Bearer `. +- URL rewriting is enabled (see specific Apache and Nginx sections) +- the server's timezone is properly defined +- the server's clock is synchronized with [NTP](https://en.wikipedia.org/wiki/Network_Time_Protocol) -JWT resources : +The host where the API client is invoked should also be synchronized with NTP, see _payload/token expiration_ -- [jwt.io](https://jwt.io) (including a list of client per language). -- RFC : https://tools.ietf.org/html/rfc7519 -- https://float-middle.com/json-web-tokens-jwt-vs-sessions/ -- HackerNews thread: https://news.ycombinator.com/item?id=11929267 +## Clients and examples + +- **[python-shaarli-client](https://github.com/shaarli/python-shaarli-client)** - the reference API client ([Documentation](http://python-shaarli-client.readthedocs.io/en/latest/)) +- [shaarli-client](https://www.npmjs.com/package/shaarli-client) - NodeJs client ([source code](https://github.com/laBecasse/shaarli-client)) by [laBecasse](https://github.com/laBecasse) +- [Android client example with Kotlin](https://gitlab.com/snippets/1665808) by [Braincoke](https://github.com/Braincoke) -### Shaarli JWT Token -JWT tokens are composed by three parts, separated by a dot `.` and encoded in base64: +This example uses the [PHP cURL](http://php.net/manual/en/book.curl.php) library. + +```php +`. +- JWT tokens are composed by three parts, separated by a dot `.` and encoded in base64: ``` [header].[payload].[signature] ``` -#### Header +##### Header Shaarli only allow one hash algorithm, so the header will always be the same: @@ -41,11 +97,9 @@ Encoded in base64, it gives: ewogICAgICAgICJ0eXAiOiAiSldUIiwKICAgICAgICAiYWxnIjogIkhTNTEyIgogICAgfQ== ``` -#### Payload +##### Payload -**Validity duration** - -To avoid infinite token validity, JWT tokens must include their creation date in UNIX timestamp format (timezone independant - UTC) under the key `iat` (issued at). This token will be accepted during 9 minutes. +Token expiration: To avoid infinite token validity, JWT tokens must include their creation date in UNIX timestamp format (timezone independent - UTC) under the key `iat` (issued at) field ([1](https://tools.ietf.org/html/rfc7519#section-4.1.6)). This token will be valid during **9 minutes**. ```json { @@ -53,14 +107,11 @@ To avoid infinite token validity, JWT tokens must include their creation date in } ``` -See [RFC reference](https://tools.ietf.org/html/rfc7519#section-4.1.6). - - -#### Signature +##### Signature -The signature authenticate the token validity. It contains the base64 of the header and the body, separated by a dot `.`, hashed in SHA512 with the API secret available in Shaarli administration page. +The signature authenticates the token validity. It contains the base64 of the header and the body, separated by a dot `.`, hashed in SHA512 with the API secret available in Shaarli administration page. -Signature example with PHP: +Example signature with PHP: ```php $content = base64_encode($header) . '.' . base64_encode($payload); @@ -68,54 +119,32 @@ $signature = hash_hmac('sha512', $content, $secret); ``` -### Complete examples -### PHP +## Troubleshooting -This example uses the [PHP cURL](http://php.net/manual/en/book.curl.php) library. +### Debug mode -```php - This should never be used in a production environment. -function base64url_encode($data) { - return rtrim(strtr(base64_encode($data), '+/', '-_'), '='); -} +For security reasons, authentication issues will always return an `HTTP 401` error code without any detail. -function generateToken($secret) { - $header = base64url_encode('{ - "typ": "JWT", - "alg": "HS512" - }'); - $payload = base64url_encode('{ - "iat": '. time() .' - }'); - $signature = base64url_encode(hash_hmac('sha512', $header .'.'. $payload , $secret, true)); - return $header . '.' . $payload . '.' . $signature; -} +It is possible to enable the debug mode in `config.json.php` +to get the actual error message in the HTTP response body with: +```json +{ + "dev": { + "debug": true + } +} +``` -function getInfo($baseUrl, $secret) { - $token = generateToken($secret); - $endpoint = rtrim($baseUrl, '/') . '/api/v1/info'; +## References - $headers = [ - 'Content-Type: text/plain; charset=UTF-8', - 'Authorization: Bearer ' . $token, - ]; +- [jwt.io](https://jwt.io) (including a list of client per language). +- [RFC - JSON Web Token (JWT)](https://tools.ietf.org/html/rfc7519) +- [JSON Web Tokens (JWT) vs Sessions](https://float-middle.com/json-web-tokens-jwt-vs-sessions/), [HackerNews thread](https://news.ycombinator.com/item?id=11929267) - $ch = curl_init($endpoint); - curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); - curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); - curl_setopt($ch, CURLOPT_AUTOREFERER, 1); - curl_setopt($ch, CURLOPT_FRESH_CONNECT, 1); - $result = curl_exec($ch); - curl_close($ch); - return $result; -} -var_dump(getInfo($baseUrl, $secret)); -```