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.

94 lines
3.8 KiB

  1. <div class="narrow">
  2. <?= partial('partials/header') ?>
  3. <?php ob_start() ?>
  4. ## Creating a Micropub Endpoint
  5. After a client has obtained an access token and discovered the user's Micropub endpoint
  6. it is ready to make requests to create posts.
  7. ### The Request
  8. This is not intended to be a comprehensive guide to Micropub, and only includes the
  9. fields that this client sends.
  10. The request to create a post will be sent with as a standard HTTP form-encoded request
  11. The example code here is written in PHP but the idea is applicable in any language.
  12. The request will contain the following POST parameters:
  13. * `h=entry` - Indicates the type of object being created, in this case an <a href="">h-entry</a>.
  14. * `content` - The text content the user entered
  15. * `category` - A comma-separated list of tags that you entered
  16. * `location` - A "geo" URI including the latitude and longitude of the photo if included. (Will look like `geo:37.786971,-122.399677;u=50`, where u=50 indicates the "uncertainty" of the location in meters)
  17. * `in-reply-to` - If set, this is a URL that the post is in reply to
  18. The request will also contain an access token in the HTTP `Authorization` header:
  19. <pre>
  20. Authorization: Bearer XXXXXXXX
  21. </pre>
  22. ### Verifying Access Tokens
  23. Before you can begin processing the request, you must first verify the access token is valid
  24. and contains at least the "post" scope.
  25. How exactly you do this is dependent on your architecture. You can query the token endpoint
  26. to check if an access token is still valid. See <a href=""></a>
  27. for more information.
  28. Once you have looked up the token info, you need to make a determination
  29. about whether that access token is still valid. You'll have the following information
  30. at hand that can be used to check:
  31. * `me` - The user who this access token corresponds to.
  32. * `client_id` - The app that generated the token.
  33. * `scope` - The list of scopes that were authorized by the user.
  34. * `issued_at` - The date the token was issued.
  35. Keep in mind that it may be possible for another user besides yourself to have created
  36. an access token at your token endpoint, so the first thing you'll do when verifying
  37. is making sure the "me" parameter matches your own domain. This way you are the only
  38. one that can create posts on your website.
  39. ### Validating the Request Parameters
  40. A valid request to create a post will contain the parameters listed above. For now,
  41. you can verify the presence of everything in the list, or you can try to genericize your
  42. micropub endpoint so that it can also create <a href="">photo posts</a>.
  43. At a bare minimum, a Micropub request will contain the following:
  44. * `h=entry`
  45. * `content`
  46. The access token must also contain at least the "post" scope.
  47. ### The Response
  48. Once you've validated the access token and checked for the presence of all required parameters,
  49. you can create a post in your website with the information provided.
  50. If a post was successfully created, the endpoint must return an `HTTP 201` response with a
  51. `Location` header that points to the URL of the post. No body is required for the response.
  52. <pre>
  53. HTTP/1.1 201 Created
  54. Location:
  55. </pre>
  56. If there was an error, the response should include an HTTP error code as appropriate,
  57. and optionally an HTML or other body with more information. Below is a list of possible errors.
  58. * `HTTP 401 Unauthorized` - No access token was provided in the request.
  59. * `HTTP 403 Forbidden` - An access token was provided, but the authenticated user does not have permission to complete the request.
  60. * `HTTP 400 Bad Request` - Something was wrong with the request, such as a missing "h" parameter, or other missing data. The response body may contain more human-readable information about the error.
  61. <?= Markdown(ob_get_clean()) ?>
  62. </div>