From 8702f795912c483557755118e5d6c9b74ca841f8 Mon Sep 17 00:00:00 2001
From: Martin Mahner <martin@mahner.org>
Date: Tue, 7 Jan 2014 13:36:02 +0100
Subject: [PATCH] Added API docs. Fixes issue #38.

---
 docs/api.rst   | 56 ++++++++++++++++++++++++++++++++++++++++++++++++++
 docs/index.rst |  1 +
 2 files changed, 57 insertions(+)
 create mode 100644 docs/api.rst

diff --git a/docs/api.rst b/docs/api.rst
new file mode 100644
index 0000000..ebd6ded
--- /dev/null
+++ b/docs/api.rst
@@ -0,0 +1,56 @@
+===
+API
+===
+
+dpaste provides a simple API endpoint to create new snippets. All you need to
+do is a simple ``POST`` request to the API endpoint ``/api/``::
+
+
+    POST http://dpaste.de/api/
+
+
+Available POST data for an API call:
+----------------------------------------
+
+``content`` (required)
+~~~~~~~~~~~~~~~~~~~~~~
+
+Required. The UTF-8 encoded string you want to paste.
+
+``lexer`` (optional)
+~~~~~~~~~~~~~~~~~~~~
+
+Optional. The lexer string key used for highlighting. See `lexer list`_  for
+a full list of choices. Default: ``python``.
+
+``format`` (optional)
+~~~~~~~~~~~~~~~~~~~~~
+
+Optional. The format of the API response. Choices are:
+
+* ``default`` — Returns a full qualified URL wrapped in quotes. Example::
+
+    "https://dpaste.de/xsWd"
+
+* ``url`` — Returns the full qualified URL to the snippet, without breaks,
+  but with a line break. Example::
+
+    https://dpaste.de/xsWd\n
+
+* ``json`` — Returns a JSON object containing the URL, lexer and content of the
+  the snippet. Example::
+
+
+    {
+        "url": "https://dpaste.de/xsWd",
+        "lexer": "python",
+        "conent": "The text body of the snippet."
+    }
+
+.. hint:: You need to adjust the setting ``DPASTE_BASE_URL`` which is used
+    to generate the full qualified URL in the API response. See :doc:`settings`.
+
+.. note:: When creating new snippets via the API, they won't be listed on the
+    history page since they are related to a browser session.
+
+.. _lexer list: https://github.com/bartTC/dpaste/blob/master/dpaste/highlight.py#L25
diff --git a/docs/index.rst b/docs/index.rst
index 34c5007..e2801e5 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -14,6 +14,7 @@ Contents:
    testing
    integration
    settings
+   api
 
 ..
     Indices and tables