From 43ad7c8e825057747ccf02049050b323878952a7 Mon Sep 17 00:00:00 2001 From: VirtualTam Date: Sat, 5 Aug 2017 11:56:24 +0200 Subject: documentation: fix rendering and internal references This is mainly cleanup after switching from Github-flavoured Markdown rendered by Github Pages, to standard Markdown rendered by MkDocs. Changed: - rephrase some section titles Fixed: - list rendering (items, sub-items)) - code rendering - quotes - dead links Removed: - extraneous navigational elements Signed-off-by: VirtualTam --- doc/md/REST-API.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'doc/md/REST-API.md') diff --git a/doc/md/REST-API.md b/doc/md/REST-API.md index 8f3f7303..f872744e 100644 --- a/doc/md/REST-API.md +++ b/doc/md/REST-API.md @@ -10,10 +10,10 @@ This token has to be included as an HTTP header called `Authentication: Bearer < JWT resources : - * [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 +- [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 ### Shaarli JWT Token -- cgit v1.2.3 From e62486dd6a76fc77f062b81c861eb3ee807b1682 Mon Sep 17 00:00:00 2001 From: VirtualTam Date: Sat, 5 Aug 2017 14:15:59 +0200 Subject: documentation: rewrite the REST API PHP client example Closes https://github.com/shaarli/Shaarli/issues/905 Relates to https://github.com/shaarli/Shaarli/pull/751 See https://shaarli.github.io/api-documentation/ Signed-off-by: VirtualTam --- doc/md/REST-API.md | 57 +++++++++++++++++++++++++++++++++++------------------- 1 file changed, 37 insertions(+), 20 deletions(-) (limited to 'doc/md/REST-API.md') diff --git a/doc/md/REST-API.md b/doc/md/REST-API.md index f872744e..ad407749 100644 --- a/doc/md/REST-API.md +++ b/doc/md/REST-API.md @@ -68,37 +68,54 @@ $signature = hash_hmac('sha512', $content, $secret); ``` -### Complete example +### Complete examples -#### PHP +### PHP + +This example uses the [PHP cURL](http://php.net/manual/en/book.curl.php) library. ```php + `ewogICAgICAgICJ0eXAiOiAiSldUIiwKICAgICAgICAiYWxnIjogIkhTNTEyIgogICAgfQ==.ewogICAgICAgICJpYXQiOiAxNDY4NjY3MDQ3CiAgICB9.1d2c54fa947daf594fdbf7591796195652c8bc63bffad7f6a6db2a41c313f495a542cbfb595acade79e83f3810d709b4251d7b940bbc10b531a6e6134af63a68` +function getInfo($baseUrl, $secret) { + $token = generateToken($secret); + $endpoint = rtrim($baseUrl, '/') . '/api/v1/info'; -```php -$options = [ - 'http' => [ - 'method' => 'GET', - 'jwt' => $token, - ], -]; -$context = stream_context_create($options); -file_get_contents($apiEndpoint, false, $context); + $headers = [ + 'Content-Type: text/plain; charset=UTF-8', + 'Authorization: Bearer ' . $token, + ]; + + $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)); ``` -- cgit v1.2.3 From 61f63d1086b2181ef92976338e593414199d1275 Mon Sep 17 00:00:00 2001 From: VirtualTam Date: Sat, 5 Aug 2017 14:30:43 +0200 Subject: documentation: add links to example REST API clients Signed-off-by: VirtualTam --- doc/md/REST-API.md | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) (limited to 'doc/md/REST-API.md') diff --git a/doc/md/REST-API.md b/doc/md/REST-API.md index ad407749..f3f0b17a 100644 --- a/doc/md/REST-API.md +++ b/doc/md/REST-API.md @@ -68,7 +68,12 @@ $signature = hash_hmac('sha512', $content, $secret); ``` -### Complete examples +## Clients and examples +### Android, Java, Kotlin + +- [Android client example with Kotlin](https://gitlab.com/snippets/1665808) + by [Braincoke](https://github.com/Braincoke) + ### PHP @@ -119,3 +124,11 @@ function getInfo($baseUrl, $secret) { var_dump(getInfo($baseUrl, $secret)); ``` + + +### Python + +See the reference API client: + +- [Documentation](http://python-shaarli-client.readthedocs.io/en/latest/) on ReadTheDocs +- [python-shaarli-client](https://github.com/shaarli/python-shaarli-client) on Github -- cgit v1.2.3 From f320efd689f17737ccbdef46cdc430d9e637b807 Mon Sep 17 00:00:00 2001 From: VirtualTam Date: Sat, 5 Aug 2017 14:46:05 +0200 Subject: documentation: elaborate on REST API server & client prerequisites Relates to https://github.com/shaarli/Shaarli/issues/903 Relates to https://github.com/shaarli/Shaarli/issues/905 Signed-off-by: VirtualTam --- doc/md/REST-API.md | 22 ++++++++++++++++++---- 1 file changed, 18 insertions(+), 4 deletions(-) (limited to 'doc/md/REST-API.md') diff --git a/doc/md/REST-API.md b/doc/md/REST-API.md index f3f0b17a..0b8aba8a 100644 --- a/doc/md/REST-API.md +++ b/doc/md/REST-API.md @@ -1,6 +1,18 @@ -## Usage +## Usage and Prerequisites -See the [REST API documentation](http://shaarli.github.io/api-documentation/). +See the [REST API documentation](http://shaarli.github.io/api-documentation/) +for a list of available endpoints and parameters. + +Please ensure that your server meets the [requirements](Server-requirements) +and is properly [configured](Server-configuration): + +- 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) + +The host where the API client is invoked should also be synchronized with NTP, +see [token expiration](#payload). ## Authentication @@ -43,9 +55,11 @@ ewogICAgICAgICJ0eXAiOiAiSldUIiwKICAgICAgICAiYWxnIjogIkhTNTEyIgogICAgfQ== #### Payload -**Validity duration** +**Token expiration** -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. +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). +This token will be valid during **9 minutes**. ```json { -- cgit v1.2.3