docs: Add a small introduction to the REST API

Signed-off-by: Damien Lespiau <damien.lespiau@intel.com>
dlespiau · Oct 25, 2015 · f3b3b18 · f3b3b18
1 parent 6ca842d
commit f3b3b18
Show file tree

Hide file tree

Showing 3 changed files with 27 additions and 0 deletions.
diff --git a/docs/manual.rst b/docs/manual.rst
@@ -1,6 +1,8 @@
 User Manual
 ===========
 
+.. _submitting-patches:
+
 Submitting patches
 ------------------
 

diff --git a/docs/rest.rst b/docs/rest.rst
@@ -1,6 +1,27 @@
 REST API
 ========
 
+Patchwork exposes a REST API to allow other systems and scripts to interact
+with it. The basic service it offers is exposing a mailing-list used for
+sending patches and review comments as high level objects: series, revisions
+and patches.
+
+**series**
+    A collection of revisions. Series objects are created, along with an
+    initial revision, when a set of patches are sent to a mailing-list,
+    usually through |git send-email|. Series can evolve over time and gain new
+    revisions as the work matures through reviews, testing and new iterations.
+
+    More about series and revisions can be found in :ref:`submitting-patches`
+
+**revision**
+    A collection of patches.
+
+**patch**
+    The usual collection of changes expressed as a diff_. With |git|, a patch
+    also contains full commit metadata.
+
+
 API metadata
 ------------
 
@@ -438,3 +459,5 @@ API Revisions
 
 - Initial revision. Basic objects exposed: api root, projects, series,
   revisions and patches.
+
+.. include:: symbols
diff --git a/docs/symbols b/docs/symbols
@@ -1,5 +1,7 @@
+.. |git| replace:: :command:`git`
 .. |git-pw| replace:: :command:`git-pw`
 .. |git send-email| replace:: :command:`git send-email`
 .. |pip| replace:: :command:`pip`
 
+.. _diff: https://en.wikipedia.org/wiki/Diff_utility
 .. _repository: https://github.com/dlespiau/patchwork