You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

152 lines
6.4 KiB

  1. <?
  2. use \Michelf\MarkdownExtra;
  3. $this->layout('layout-loggedin', ['title' => $title, 'accounts' => $accounts, 'user' => $user, 'return_to' => $return_to]);
  4. ?>
  5. <div class="ui main text container api-docs" style="margin-top: 80px;">
  6. <h1>Telegraph API</h1>
  7. <? ob_start(); ?>
  8. <h2 class="ui dividing header" id="send">Send a webmention to a specific page</h2>
  9. Post to `https://telegraph.p3k.io/webmention`
  10. * `token` - your API key obtained after signing up
  11. * `source` - the URL of your post
  12. * `target` OR `target_domain` - the URL or domain you linked to, respectively
  13. * `callback` - (optional) - a URL that will receive a web hook when new information about this webmention is available
  14. 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.
  15. 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.
  16. If you pass `target_domain` instead of `target`, Telegraph will find and enqueue webmentions for all links to that domain.
  17. #### Errors
  18. * `authentication_required` - the token parameter was missing
  19. * `invalid_token` - the token was invalid or expired
  20. * `missing_parameters` - one or more of the three parameters were not in the request
  21. * `invalid_parameter` - one or more of the parameters were invalid, e.g. the target was not a valid URL
  22. * `source_not_html` - the source document could not be parsed as HTML (only in extreme cases, most of the time it just accepts whatever)
  23. * `no_link_found` - the link to the target URL was not found on the source document
  24. * `not_supported` - the target URL is known to not accept webmentions, so the request is rejected before even queuing it. If you believe this is in error, please file an issue at [github.com/aaronpk/Telegraph/issues](https://github.com/aaronpk/Telegraph/issues)
  25. An error response in this case will be returned with an HTTP 400 status code an a JSON body:
  26. ```
  27. HTTP/1.1 400 Bad Request
  28. Content-type: application/json
  29. {
  30. "error": "missing_parameters",
  31. "error_description": "The source or target parameters were missing"
  32. }
  33. ```
  34. #### Success
  35. 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.
  36. ```
  37. HTTP/1.1 201 Created
  38. Content-type: application/json
  39. Location: https://telegraph.p3k.io/webmention/xxxxxxxx
  40. {
  41. "status": "queued",
  42. "location": "https://telegraph.p3k.io/webmention/xxxxxxxx"
  43. }
  44. ```
  45. If you use `target_domain` instead of `target`, the `location` field will be a list containing the status URLs for each webmention that was queued. The `Location` header will be omitted.
  46. ```
  47. HTTP/1.1 201 Created
  48. Content-type: application/json
  49. {
  50. "status": "queued",
  51. "location": [
  52. "https://telegraph.p3k.io/webmention/xxxxxxxx",
  53. "https://telegraph.p3k.io/webmention/yyyyyyyy"
  54. ]
  55. }
  56. ```
  57. <h2 class="ui dividing header" id="status">Status API</h2>
  58. 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:
  59. ```
  60. HTTP/1.1 200 OK
  61. Content-Type: application/json
  62. {
  63. "status": "queued",
  64. "summary": "The webmention is still in the processing queue.",
  65. "location": "https://telegraph.p3k.io/webmention/xxxxxxxx"
  66. }
  67. ```
  68. ```
  69. HTTP/1.1 200 OK
  70. Content-Type: application/json
  71. {
  72. "status": "no_link_found",
  73. "summary": "No link was found from source to target"
  74. }
  75. ```
  76. ```
  77. HTTP/1.1 200 OK
  78. Content-Type: application/json
  79. {
  80. "status": "success",
  81. "type": "webmention",
  82. "endpoint":
  83. "summary": "The webmention request was accepted.",
  84. "location": "https://telegraph.p3k.io/webmention/xxxxxxxx"
  85. }
  86. ```
  87. The possible fields that are returned are as follows:
  88. * `status` - One of the status codes listed below
  89. * `type` - optional - "webmention" or "pingback", depending on what was discovered at the target
  90. * `endpoint` - optional - The webmention or pingback endpoint that was discovered
  91. * `http_code` - optional - The HTTP code that the webmention or pingback endpoint returned
  92. * `summary` - optional - A human-readable summary of the status
  93. * `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.
  94. Other possible status codes are listed below.
  95. * `accepted` - the webmention or pingback request was accepted (pingback does not differentiate between when a request is queued or processed immediately)
  96. * `success` - the webmention status endpoint indicated the webmention was successful after processing it
  97. * `not_supported` - no webmention or pingback endpoint was found at the target
  98. * `no_link_found` - no link was found from source to target
  99. 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.
  100. <h2 class="ui dividing header" id="callbacks">Callback Events</h2>
  101. 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.
  102. 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.
  103. 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.
  104. A callback from Telegraph will include the following post body parameters:
  105. * `source` - the URL of your post
  106. * `target` - the URL you linked to
  107. * `type` - "pingback" or "webmention" depending on what was discovered at the target
  108. * `status` - one of the status codes above, e.g. `accepted`
  109. * `location` - if further updates will be available, the status URL where you can check again in the future
  110. <?
  111. $source=ob_get_clean();
  112. echo MarkdownExtra::defaultTransform($source);
  113. ?>
  114. </div>