From e7e3499e110d2a371cc9d6e62989ecb105eb7e61 Mon Sep 17 00:00:00 2001 From: Aaron Parecki Date: Thu, 24 Dec 2015 11:43:56 -0800 Subject: [PATCH] add API docs and finishing touches on copy/layout --- README.md | 121 +------------------------------ composer.json | 3 +- composer.lock | 55 +++++++++++++- controllers/Auth.php | 16 +++-- controllers/Controller.php | 21 ++++++ public/assets/styles.css | 11 +++ views/api.php | 134 +++++++++++++++++++++++++++++++++++ views/dashboard.php | 15 +++- views/footer-block.php | 31 ++++++++ views/index.php | 110 +++++++++++++++------------- views/layout-loggedin.php | 39 ++++++---- views/layout.php | 5 +- views/webmention-details.php | 2 +- views/webmention-send.php | 13 +++- 14 files changed, 376 insertions(+), 200 deletions(-) create mode 100644 public/assets/styles.css create mode 100644 views/api.php create mode 100644 views/footer-block.php diff --git a/README.md b/README.md index acc9ac4..f044804 100644 --- a/README.md +++ b/README.md @@ -2,126 +2,9 @@ Telegraph is an API for sending [Webmentions](http://webmention.net). -## Send a webmention to a specific page -Post to `https://telegraph.p3k.io/webmention` - -* `token` - your API key obtained after signing up -* `source` - the URL of your post -* `target` - the URL you linked to -* `callback` - (optional) - a URL that will receive a web hook when new information about this webmention is available - -The Telegraph API will validate the parameters and then queue the webmention for sending. If there was a problem with the request, you will get an error response immediately. - -The API will first make an HTTP request to the source URL, and look for a link to the target on the page. This happens synchronously so you will get this error reply immediately. - -#### Errors -* `authentication_required` - the token parameter was missing -* `invalid_token` - the token was invalid or expired -* `missing_parameters` - one or more of the three parameters were not in the request -* `invalid_parameter` - one or more of the parameters were invalid, e.g. the target was not a valid URL -* `source_not_html` - the source document could not be parsed as HTML (only in extreme cases, most of the time it just accepts whatever) -* `no_link_found` - the link to the target URL was not found on the source document - -An error response in this case will be returned with an HTTP 400 status code an a JSON body: - -```json -HTTP/1.1 400 Bad Request -Content-type: application/json - -{ - "error": "missing_parameters", - "error_description": "The source or target parameters were missing" -} -``` - -#### Success - -If the initial validation succeeds, Telegraph will queue the webmention for sending and return a success response, including a URL you can check for status updates. This URL will be returned even if you also provide a callback URL. The URL will be available in both the `Location` header as well as in the JSON response. - -``` -HTTP/1.1 201 Created -Content-type: application/json -Location: https://telegraph.p3k.io/webmention/xxxxxxxx - -{ - "status": "queued", - "location": "https://telegraph.p3k.io/webmention/xxxxxxxx" -} -``` - -### Status API - -You can poll the status URL returned after queuing a webmention for more information on the progress of sending the webmention. The response will look like the following: - -``` -HTTP/1.1 200 OK -Content-Type: application/json - -{ - "status": "queued", - "summary": "The webmention is still in the processing queue.", - "location": "https://telegraph.p3k.io/webmention/xxxxxxxx" -} -``` - -``` -HTTP/1.1 200 OK -Content-Type: application/json - -{ - "status": "no_link_found", - "summary": "No link was found from source to target" -} -``` - -``` -HTTP/1.1 200 OK -Content-Type: application/json - -{ - "status": "success", - "type": "webmention", - "endpoint": - "summary": "The webmention request was accepted.", - "location": "https://telegraph.p3k.io/webmention/xxxxxxxx" -} -``` - -The possible fields that are returned are as follows: - -* `status` - One of the status codes listed below -* `type` - optional - "webmention" or "pingback", depending on what was discovered at the target -* `endpoint` - optional - The webmention or pingback endpoint that was discovered -* `http_code` - optional - The HTTP code that the webmention or pingback endpoint returned -* `summary` - optional - A human-readable summary of the status -* `location` - optional - If present, you can continue checking this URL for status updates. If not present, no further information will be available about this request. - -Other possible status codes are listed below. - -* `accepted` - the webmention or pingback request was accepted (pingback does not differentiate between when a request is queued or processed immediately) -* `success` - the webmention status endpoint indicated the webmention was successful after processing it -* `not_supported` - no webmention or pingback endpoint was found at the target -* `no_link_found` - no link was found from source to target - -Other status codes may be returned depending on the receiver's status endpoint. You should only assume a webmention was successfully sent if the status is `success` or `accepted`. If the response does not contain a `location` parameter you should not continue polling the endpoint. - - -### Callback Events -After Telegraph processes your request, you will receive a post to the callback URL. The initial callback you receive will be one of the status codes returned by the status API. - -Typically, webmention endpoints defer processing until later, so normally the first callback received will indicate that the webmention was queued. This callback will normally be sent relatively quickly after you make the initial request, typically within a few seconds. - -If the webmention endpoint provides status updates, either through a status URL or web hook, then Telegraph will deliver follow-up notifications when it gets updated information. - -A callback from Telegraph will include the following post body parameters: - -* `source` - the URL of your post -* `target` - the URL you linked to -* `type` - "pingback" or "webmention" depending on what was discovered at the target -* `status` - one of the status codes above, e.g. `accepted` -* `location` - if further updates will be available, the status URL where you can check again in the future - +## API +See https://telegraph.p3k.io/api ## Credits diff --git a/composer.json b/composer.json index 9e52fc9..7f1f15d 100644 --- a/composer.json +++ b/composer.json @@ -10,7 +10,8 @@ "league/plates": "~3.1", "j4mie/idiorm": "1.5.*", "p3k/caterpillar": "0.1.*", - "predis/predis": "1.*" + "predis/predis": "1.*", + "michelf/php-markdown": "1.6.*" }, "require-dev": { "phpunit/phpunit": "*" diff --git a/composer.lock b/composer.lock index 98fabcf..436e58e 100644 --- a/composer.lock +++ b/composer.lock @@ -4,8 +4,8 @@ "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#composer-lock-the-lock-file", "This file is @generated automatically" ], - "hash": "608bb1b12f4959a9b2dccdd64046ac57", - "content-hash": "eefd85cb3d0c9cf1666ed057a450544d", + "hash": "fe88436a4cf4b629d33a4969c34cefa5", + "content-hash": "40f23b807dfa9bbd43f7542fa5c41faa", "packages": [ { "name": "barnabywalters/mf-cleaner", @@ -541,6 +541,57 @@ ], "time": "2015-07-12 14:10:01" }, + { + "name": "michelf/php-markdown", + "version": "1.6.0", + "source": { + "type": "git", + "url": "https://github.com/michelf/php-markdown.git", + "reference": "156e56ee036505ec637d761ee62dc425d807183c" + }, + "dist": { + "type": "zip", + "url": "https://api.github.com/repos/michelf/php-markdown/zipball/156e56ee036505ec637d761ee62dc425d807183c", + "reference": "156e56ee036505ec637d761ee62dc425d807183c", + "shasum": "" + }, + "require": { + "php": ">=5.3.0" + }, + "type": "library", + "extra": { + "branch-alias": { + "dev-lib": "1.4.x-dev" + } + }, + "autoload": { + "psr-0": { + "Michelf": "" + } + }, + "notification-url": "https://packagist.org/downloads/", + "license": [ + "BSD-3-Clause" + ], + "authors": [ + { + "name": "Michel Fortin", + "email": "michel.fortin@michelf.ca", + "homepage": "https://michelf.ca/", + "role": "Developer" + }, + { + "name": "John Gruber", + "homepage": "https://daringfireball.net/" + } + ], + "description": "PHP Markdown", + "homepage": "https://michelf.ca/projects/php-markdown/", + "keywords": [ + "markdown" + ], + "time": "2015-12-24 01:37:31" + }, { "name": "nikic/fast-route", "version": "v0.7.0", diff --git a/controllers/Auth.php b/controllers/Auth.php index 9081f8b..b20ca70 100644 --- a/controllers/Auth.php +++ b/controllers/Auth.php @@ -6,16 +6,22 @@ use \Firebase\JWT\JWT; class Auth { public function login(Request $request, Response $response) { - $response->setContent(view('login', [ - 'title' => 'Sign In to Telegraph', - 'return_to' => $request->get('return_to') - ])); + session_start(); + if(session('user_id')) { + $response->setStatusCode(302); + $response->headers->set('Location', '/dashboard'); + } else { + $response->setContent(view('login', [ + 'title' => 'Sign In to Telegraph', + 'return_to' => $request->get('return_to') + ])); + } return $response; } public function logout(Request $request, Response $response) { session_start(); - if(array_key_exists('user_id', $_SESSION)) { + if(session('user_id')) { $_SESSION['user_id'] = null; session_destroy(); } diff --git a/controllers/Controller.php b/controllers/Controller.php index f528576..49b8904 100644 --- a/controllers/Controller.php +++ b/controllers/Controller.php @@ -47,6 +47,27 @@ class Controller { return $response; } + public function api(Request $request, Response $response) { + session_start(); + if(session('user_id')) { + $role = $this->_get_role($request, $response); + $site = ORM::for_table('sites')->where_id_is($role->site_id)->find_one(); + } else { + $role = false; + $site = false; + } + + $response->setContent(view('api', [ + 'title' => 'Telegraph API Documentation', + 'user' => $this->_user(), + 'accounts' => $this->_accounts(), + 'site' => $site, + 'role' => $role, + 'return_to' => $request->getRequestURI() + ])); + return $response; + } + private static function _icon_for_status($status) { switch($status) { case 'success': diff --git a/public/assets/styles.css b/public/assets/styles.css new file mode 100644 index 0000000..33bf70a --- /dev/null +++ b/public/assets/styles.css @@ -0,0 +1,11 @@ +.footer.segment { + padding: 5em 0em; +} + +.api-docs pre { + padding: 8px 12px; + border-radius: 4px; + border: 1px #ddd solid; + background-color: rgba(248,246,255,1); + font-size: 0.9em; +} diff --git a/views/api.php b/views/api.php new file mode 100644 index 0000000..6967989 --- /dev/null +++ b/views/api.php @@ -0,0 +1,134 @@ +layout('layout-loggedin', ['title' => $title, 'accounts' => $accounts, 'user' => $user, 'return_to' => $return_to]); +?> + +
+ +

Telegraph API

+ + +

Send a webmention to a specific page

+Post to `https://telegraph.p3k.io/webmention` + +* `token` - your API key obtained after signing up +* `source` - the URL of your post +* `target` - the URL you linked to +* `callback` - (optional) - a URL that will receive a web hook when new information about this webmention is available + +The Telegraph API will validate the parameters and then queue the webmention for sending. If there was a problem with the request, you will get an error response immediately. + +The API will first make an HTTP request to the source URL, and look for a link to the target on the page. This happens synchronously so you will get this error reply immediately. + +#### Errors +* `authentication_required` - the token parameter was missing +* `invalid_token` - the token was invalid or expired +* `missing_parameters` - one or more of the three parameters were not in the request +* `invalid_parameter` - one or more of the parameters were invalid, e.g. the target was not a valid URL +* `source_not_html` - the source document could not be parsed as HTML (only in extreme cases, most of the time it just accepts whatever) +* `no_link_found` - the link to the target URL was not found on the source document + +An error response in this case will be returned with an HTTP 400 status code an a JSON body: + +``` +HTTP/1.1 400 Bad Request +Content-type: application/json + +{ + "error": "missing_parameters", + "error_description": "The source or target parameters were missing" +} +``` + +#### Success + +If the initial validation succeeds, Telegraph will queue the webmention for sending and return a success response, including a URL you can check for status updates. This URL will be returned even if you also provide a callback URL. The URL will be available in both the `Location` header as well as in the JSON response. + +``` +HTTP/1.1 201 Created +Content-type: application/json +Location: https://telegraph.p3k.io/webmention/xxxxxxxx + +{ + "status": "queued", + "location": "https://telegraph.p3k.io/webmention/xxxxxxxx" +} +``` + +

Status API

+ +You can poll the status URL returned after queuing a webmention for more information on the progress of sending the webmention. The response will look like the following: + +``` +HTTP/1.1 200 OK +Content-Type: application/json + +{ + "status": "queued", + "summary": "The webmention is still in the processing queue.", + "location": "https://telegraph.p3k.io/webmention/xxxxxxxx" +} +``` + +``` +HTTP/1.1 200 OK +Content-Type: application/json + +{ + "status": "no_link_found", + "summary": "No link was found from source to target" +} +``` + +``` +HTTP/1.1 200 OK +Content-Type: application/json + +{ + "status": "success", + "type": "webmention", + "endpoint": + "summary": "The webmention request was accepted.", + "location": "https://telegraph.p3k.io/webmention/xxxxxxxx" +} +``` + +The possible fields that are returned are as follows: + +* `status` - One of the status codes listed below +* `type` - optional - "webmention" or "pingback", depending on what was discovered at the target +* `endpoint` - optional - The webmention or pingback endpoint that was discovered +* `http_code` - optional - The HTTP code that the webmention or pingback endpoint returned +* `summary` - optional - A human-readable summary of the status +* `location` - optional - If present, you can continue checking this URL for status updates. If not present, no further information will be available about this request. + +Other possible status codes are listed below. + +* `accepted` - the webmention or pingback request was accepted (pingback does not differentiate between when a request is queued or processed immediately) +* `success` - the webmention status endpoint indicated the webmention was successful after processing it +* `not_supported` - no webmention or pingback endpoint was found at the target +* `no_link_found` - no link was found from source to target + +Other status codes may be returned depending on the receiver's status endpoint. You should only assume a webmention was successfully sent if the status is `success` or `accepted`. If the response does not contain a `location` parameter you should not continue polling the endpoint. + + +

Callback Events

+After Telegraph processes your request, you will receive a post to the callback URL. The initial callback you receive will be one of the status codes returned by the status API. + +Typically, webmention endpoints defer processing until later, so normally the first callback received will indicate that the webmention was queued. This callback will normally be sent relatively quickly after you make the initial request, typically within a few seconds. + +If the webmention endpoint provides status updates, either through a status URL or web hook, then Telegraph will deliver follow-up notifications when it gets updated information. + +A callback from Telegraph will include the following post body parameters: + +* `source` - the URL of your post +* `target` - the URL you linked to +* `type` - "pingback" or "webmention" depending on what was discovered at the target +* `status` - one of the status codes above, e.g. `accepted` +* `location` - if further updates will be available, the status URL where you can check again in the future + + +
diff --git a/views/dashboard.php b/views/dashboard.php index c93610a..ad65f70 100644 --- a/views/dashboard.php +++ b/views/dashboard.php @@ -1,6 +1,6 @@ layout('layout-loggedin', ['title' => $title, 'accounts' => $accounts, 'user' => $user]); ?> -
+
Find Links @@ -28,6 +28,7 @@
+ @@ -57,6 +58,18 @@
Status
+ +
It looks like you haven't sent any webmentions yet! Try entering one of your post URLs above and send some.
+ + +
+
+ + +
+

Use this key when sending webmentions using the API.

+
+
+ @@ -15,8 +15,5 @@ section('content') ?> -
-
- diff --git a/views/webmention-details.php b/views/webmention-details.php index 7f61556..0860f96 100644 --- a/views/webmention-details.php +++ b/views/webmention-details.php @@ -1,6 +1,6 @@ layout('layout-loggedin', ['title' => $title, 'accounts' => $accounts, 'user' => $user]); ?> -
+

Webmention Request

diff --git a/views/webmention-send.php b/views/webmention-send.php index 9d34e7d..cf080af 100644 --- a/views/webmention-send.php +++ b/views/webmention-send.php @@ -1,9 +1,11 @@ layout('layout-loggedin', ['title' => $title, 'accounts' => $accounts, 'user' => $user]); ?> -
+

Send Webmentions

+ Source URL: + @@ -23,6 +25,12 @@ $(function(){ $.post('/dashboard/get_outgoing_links.json', { url: source_url }, function(data) { + if(data.links.length == 0) { + $("#send-table tbody tr:first td").html('
No links were found from the given URL. Make sure your post is marked up with h-entry and contains some links.
'); + $("#send-table").removeClass("fixed").removeClass("single").removeClass("line"); + return; + } + $("#send-table tbody").html(''); for(var i in data.links) { $("#send-table tr:last").after('' @@ -34,6 +42,7 @@ $(function(){ +'' +''); } + $("#send-table tbody tr:first").remove(); // Enable popup on any values that overflowed the container @@ -101,7 +110,7 @@ function bind_send_buttons() { .popup { word-wrap: break-word; } -#send-table tr { +#send-table tbody tr { height: 83px; }
URL