Browse Source

remove docs that are duplicated in quill and on the wiki

adds screenshot for docs page
pull/10/head
Aaron Parecki 2 years ago
parent
commit
cbb2a3f419
No known key found for this signature in database GPG Key ID: 276C2817346D6056
6 changed files with 7 additions and 3075 deletions
  1. +1
    -2
      composer.json
  2. +2
    -2
      controllers/controllers.php
  3. +0
    -2953
      lib/markdown.php
  4. BIN
      public/images/teacup-screenshot.png
  5. +0
    -94
      views/creating-a-micropub-endpoint.php
  6. +4
    -24
      views/docs.php

+ 1
- 2
composer.json View File

@@ -15,8 +15,7 @@
"files": [
"lib/Savant.php",
"lib/config.php",
"lib/helpers.php",
"lib/markdown.php"
"lib/helpers.php"
]
}
}

+ 2
- 2
controllers/controllers.php View File

@@ -117,10 +117,10 @@ $app->post('/prefs', function() use($app) {
});

$app->get('/creating-a-token-endpoint', function() use($app) {
$app->redirect('http://indiewebcamp.com/token-endpoint', 301);
$app->redirect('https://indieweb.org/token-endpoint', 301);
});
$app->get('/creating-a-micropub-endpoint', function() use($app) {
render('creating-a-micropub-endpoint', array('title' => 'Creating a Micropub Endpoint'));
$app->redirect('https://indieweb.org/Micropub', 301);
});

$app->get('/docs', function() use($app) {


+ 0
- 2953
lib/markdown.php
File diff suppressed because it is too large
View File


BIN
public/images/teacup-screenshot.png View File

Before After
Width: 750  |  Height: 1334  |  Size: 87KB

+ 0
- 94
views/creating-a-micropub-endpoint.php View File

@@ -1,94 +0,0 @@
<div class="narrow">
<?= partial('partials/header') ?>

<?php ob_start() ?>
## Creating a Micropub Endpoint

After a client has obtained an access token and discovered the user's Micropub endpoint
it is ready to make requests to create posts.

### The Request

This is not intended to be a comprehensive guide to Micropub, and only includes the
fields that this client sends.

The request to create a post will be sent with as a standard HTTP form-encoded request
The example code here is written in PHP but the idea is applicable in any language.

The request will contain the following POST parameters:

* `h=entry` - Indicates the type of object being created, in this case an <a href="http://indiewebcamp.com/h-entry">h-entry</a>.
* `content` - The text content the user entered, in this case the caption on the Instagram photo.
* `category` - A comma-separated list of tags that you entered
* `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)
* `in-reply-to` - If set, this is a URL that the post is in reply to

The request will also contain an access token in the HTTP `Authorization` header:

<pre>
Authorization: Bearer XXXXXXXX
</pre>


### Verifying Access Tokens

Before you can begin processing the photo, you must first verify the access token is valid
and contains at least the "post" scope.

How exactly you do this is dependent on your architecture. You can query the token endpoint
to check if an access token is still valid. See [https://tokens.indieauth.com/#verify tokens.indieauth.com]
for more information.

Once you have looked up the token info, you need to make a determination
about whether that access token is still valid. You'll have the following information
at hand that can be used to check:

* `me` - The user who this access token corresponds to.
* `client_id` - The app that generated the token.
* `scope` - The list of scopes that were authorized by the user.
* `issued_at` - The date the token was issued.

Keep in mind that it may be possible for another user besides yourself to have created
an access token at your token endpoint, so the first thing you'll do when verifying
is making sure the "me" parameter matches your own domain. This way you are the only
one that can create posts on your website.


### Validating the Request Parameters

A valid request to create a post will contain the parameters listed above. For now,
you can verify the presence of everything in the list, or you can try to genericize your
micropub endpoint so that it can also create [http://ownyourgram.com/creating-a-micropub-endpoint photo posts].

At a bare minimum, a Micropub request will contain the following:

* `h=entry`
* `content`

The access token must also contain at least the "post" scope.


### The Response

Once you've validated the access token and checked for the presence of all required parameters,
you can create a post in your website with the information provided.

If a post was successfully created, the endpoint must return an `HTTP 201` response with a
`Location` header that points to the URL of the post. No body is required for the response.

<pre>
HTTP/1.1 201 Created
Location: http://example.com/post/100
</pre>

If there was an error, the response should include an HTTP error code as appropriate,
and optionally an HTML or other body with more information. Below is a list of possible errors.

* `HTTP 401 Unauthorized` - No access token was provided in the request.
* `HTTP 403 Forbidden` - An access token was provided, but the authenticated user does not have permission to complete the request.
* `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.



<?= Markdown(ob_get_clean()) ?>
</div>

+ 4
- 24
views/docs.php View File

@@ -4,32 +4,12 @@
<h2 id="introduction">Introduction</h2>

<div class="col-xs-6 col-md-4" style="float: right;">
<span class="thumbnail"><img src="/images/teacup-ui.png"></span>
<span class="thumbnail"><img src="/images/teacup-screenshot.png"></span>
</div>

<p>This is a simple <a href="http://indiewebcamp.com/micropub">Micropub</a> client for
creating text posts on your own website. To use it, you will need to turn your website
into an OAuth provider, and implement a Micropub endpoint that this app will send
requests to.</p>

<p>Once you've signed in, you'll see an interface like the one shown which you can use to
write a post. Clicking "post" will make a Micropub request to your endpoint.<p>



<h2 id="endpoints">Configuring Endpoints</h2>

<h3>Authorization Endpoint</h3>
<p><i>The authorization endpoint tells this app where to direct your browser to sign you in.</i></p>
<?= partial('partials/auth-endpoint-help') ?>

<h3>Token Endpoint</h3>
<p><i>The token endpoint is where this app will make a request to get an access token after obtaining authorization.</i></p>
<?= partial('partials/token-endpoint-help') ?>

<h3>Micropub Endpoint</h3>
<p><i>The Micropub endpoint is the URL this app will use to post new photos.</i></p>
<?= partial('partials/micropub-endpoint-help') ?>
<p>Teacup is a simple <a href="https://indieweb.org/Micropub">Micropub</a> client for
posting food and drink to your website. Once you've set up Micropub on your site,
you can use this app to post the experimental food and drink posts to your site.</p>

<p>The <a href="/creating-a-micropub-endpoint">Creating a Micropub Endpoint</a> tutorial will walk you through how to handle incoming POST requests from apps like this.</p>


Loading…
Cancel
Save