dffd

drama/templates/api.html

@@ -1,5 +1,114 @@
 {% extends "default.html" %}
 
+{% block title %}
+<title>Drama - API</title>
+<meta name="description" content="Drama API Guide">
+{% endblock %}
+
 {% block content %}
-words words words
+{% filter markdown %}
+# API
+
+The OAuth2 authorization flow is used to enable users to authorize third-party applications to access their Drama account without having to provide their login information to the application.
+
+This page explains how to obtain API application keys, how to prompt a user for authorization, and how to obtain and use access tokens. 
+
+## Step 1: Create your Application
+
+In the [apps tab of Drama settings](/settings/apps), fill in and submit the form to request new API keys. You will need:
+
+* an application name
+* a Redirect URI, or a comma-separated list of redirect URIs. May not use HTTP unless using localhost (use HTTPS instead).
+* a brief description of what your application is intended to do
+
+Don't worry too much about accuracy; you will be able to change all of these later.
+
+Drama administrators will review and approve or deny your request for API keys. You'll know when your request has been approved when a client ID and secret appear in your application information.
+
+DO NOT reveal your Client Secret. Anyone with your Client Secret will be able to pretend to be you. You are responsible for keeping your Client Secret a secret!
+
+## Step 2: Prompt Your User for Authorization
+
+Send your user to `https://rdrama.net/oauth/authorize`, with the following URL parameters:
+
+* `client_id` - Your application's Client ID
+* `redirect_uri` - The redirect URI (or one of the URIs) specified in your application information. Must not use HTTP unless using localhost (use HTTPS instead). 
+* `state` - This is your own anti-cross-site-forgery token. We don't do anything with this, except give it to the user to pass back to you later. You are responsible for generating and validating the state token.
+* `scope` - A comma-separated list of permission scopes that you are requesting. Valid scopes are: `identity`, `create`, `read`, `update`, `delete` and `vote`.
+* `permanent` - optional. Set to `true` if you are requesting indefinite access. Omit if not.
+
+If done correctly, the user will see that your application wants to access their Drama account, and be prompted to approve or deny the request.
+
+## Step 3: Catch the redirect
+
+The user clicks "Authorize". Drama will redirect the user's browser to GET the designated redirect URI. The following URL parameters will be included, which your server should process:
+
+* `code` - a **single-use** authorization code.
+* `state` - The state token from earlier.
+
+Validate the state token. How you do this is up to you.
+
+## Step 4: Exchange code for access token
+
+Make a POST request to `https://rdrama.net/oauth/grant`. Include the following form parameters:
+
+* `client_id` - Your application's Client ID
+* `client_secret` - Your application's Client Secret
+* `grant_type` - Set to the word "code"
+* `code` - The `code` parameter that was given to you in the previous step.
+
+Python example:
+
+<pre>
+	import requests
+	code=request.args.get("code")
+
+	headers={"User-Agent": "sex"}
+	url="/oauth/grant"
+	data={"client_id": my_client_id,
+			"client_secret": my_client_secret,
+			"grant_type": "code",
+			"code": code
+			}
+
+	r=requests.post(url, headers=headers, data=data)
+
+	print(r.json())
+</pre>
+
+If everything is good, we will respond with the following (example) JSON body:
+
+<pre>
+	{
+	"access_token": 		#Access token
+	"scopes": 				#Comma-separated list of scopes included in authorization
+	"expires_at": 			#Unix epoch integer time at which access token expires
+	"token_type": "Bearer"
+	"refresh_token":		#This key is omitted in temporary authorizations
+	}
+</pre>
+
+Store the access and refresh tokens. You should also store expiration timestamp and the scopes list, so that you pre-emptively avoid sending requests to Drama that won't be accepted.
+
+## Step 5: Using the Access Token
+
+To use the access token, include the following header in subsequent API requests to Drama: `Authorization: Bearer access_token_goes_here`
+
+Python example, presuming that the application has obtained a valid `read` authorization:
+
+<pre>
+	import requests
+
+	headers={"Authorization": "Bearer " + access_token,
+			 "User-Agent": "Drama Reader v1 by @carpathianflorist"}
+	url="/"
+
+	r=requests.get(url, headers=headers)
+
+	print(r.json())
+</pre>
+
+The expected result of this would be a large JSON representation of the submissions that make up the user's personal front page.
+
+{% endfilter %}
 {% endblock %}