Aaron Parecki 83f84154b2 | 8 years ago | |
---|---|---|
controllers | 8 years ago | |
lib | 8 years ago | |
public | 8 years ago | |
scripts | 8 years ago | |
tests | 8 years ago | |
views | 8 years ago | |
.gitignore | 8 years ago | |
CONTRIBUTING.md | 8 years ago | |
LICENSE | 9 years ago | |
README.md | 8 years ago | |
composer.json | 8 years ago | |
composer.lock | 8 years ago | |
phpunit.xml | 8 years ago |
Telegraph is an API for sending Webmentions.
Post to https://telegraph.p3k.io/webmention
token
- your API key obtained after signing upsource
- the URL of your posttarget
- the URL you linked tocallback
- (optional) - a URL that will receive a web hook when new information about this webmention is availableThe 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.
authentication_required
- the token parameter was missinginvalid_token
- the token was invalid or expiredmissing_parameters
- one or more of the three parameters were not in the requestinvalid_parameter
- one or more of the parameters were invalid, e.g. the target was not a valid URLsource_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 documentAn 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"
}
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
{
"result": "queued",
"status": "https://telegraph.p3k.io/webmention/xxxxxxxx"
}
After Telegraph processes your request, you will receive a post to the callback URL. The initial callback you receive will be one of the following status codes:
not_supported
- no webmention or pingback endpoint foundwebmention_accepted
- the webmention request was acceptedwebmention_error
- the webmention endpoint returned an error codepingback_accepted
- pingback was accepted (pingback does not differentiate between when a request is queued or processed immediately)pingback_error
- the pingback endpoint returned an error codeTypically, 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 posttarget
- the URL you linked tostatus
- one of the status codes above, e.g. webmention_queued
Telegraph photo: https://www.flickr.com/photos/nostri-imago/3407786186
Telegraph icon: https://thenounproject.com/search/?q=telegraph&i=22058