From cbbcd70463862c5aac1c2467d70895a77bdb96b3 Mon Sep 17 00:00:00 2001
From: Mike Crute <mike@crute.us>
Date: Sun, 29 Oct 2017 04:32:32 +0000
Subject: Stub out REST API docs

---
 rest/index.rst | 84 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 84 insertions(+)
 create mode 100644 rest/index.rst

(limited to 'rest/index.rst')

diff --git a/rest/index.rst b/rest/index.rst
new file mode 100644
index 0000000..a0cd991
--- /dev/null
+++ b/rest/index.rst
@@ -0,0 +1,84 @@
+========
+REST API
+========
+
+.. toctree::
+   :maxdepth: 2
+
+   authentication
+   stations
+   bookmarks
+   account
+   ads
+   endpoints
+   errorcodes
+   implementations
+
+The Pandora REST API is used by modern Pandora apps including the website and
+the various mobile apps provided by Pandora. The current REST API has multiple
+versions and not all functionality seems to be supported for each version.
+Released API versions are stable but new APIs are added often as the Pandora
+feature set evolves. The main endpoint is:
+
+- https://www.pandora.com/api/
+
+All requests are JSON-encoded and sent via HTTP POST body to the endpoints over
+HTTPS. Response bodies are JSON-encoded values. Unlike the JSON v5 API there is
+no requirement for time syncronization, Blowfish cryptography, or partner
+logins.
+
+The API requires a cookie aware client as several cookies will be issued during
+authentication that **must** be present in every request. Failure to provide
+the cookies will result in HTTP 400 errors.
+
+.. _rest-csrf-token:
+
+CSRF Token / Cookie
+===================
+All requests require an ``X-CsrfToken`` header as well as a matching
+``csrftoken`` cookie. The current version of the API merely validates that the
+token and cookie match so the client can make up whatever they want. However,
+the token can also be obtained by making a ``HEAD`` request to
+``https://www.pandora.com/`` and saving the cookies. The API endpoints will not
+serve cookies until after authentication. Clients *SHOULD* make a ``HEAD``
+request to the root domain and include the current value of the ``csrftoken``
+cookie in each request.
+
+.. code:: http
+
+	POST /api/v1/auth/login HTTP/1.1
+	Host: www.pandora.com
+	X-CsrfToken: 123456a7889b1c23
+	X-AuthToken: 
+
+	{ "username": "foo", "password": "bar" }
+
+.. _rest-auth-token:
+
+Auth Token
+==========
+All requests except for login require an ``X-AuthToken`` header which contains
+the auth token obtained during login. It is acceptable to include the
+``X-AuthToken`` header with an empty value during login.
+
+.. code:: http
+
+	POST /api/v1/station/getStations HTTP/1.1
+	Host: www.pandora.com
+	X-CsrfToken: 123456a7889b1c23
+	X-AuthToken: dGhpcyBpcyBqdXN0IGFuIGV4YW1wbGUgY29kZQo=
+
+	{ "pageSize": 250 }
+
+Errors
+======
+Error conditions are indicated by a combination of HTTP status code and a JSON
+response body. Any responses with a 200 status code are successful.
+
+.. code:: json
+
+	{
+		"errorCode": 0,
+		"errorString": "INVALID_REQUEST",
+		"message": "The request could not be validated"
+	}
-- 
cgit v1.2.3