WIP: api page

api.rst

@@ -0,0 +1,149 @@
+Tables and Views
+================
+
+All views and tables in the active schema and accessible by the active database role for a request are available for querying. They are exposed in one-level deep routes. For instance the full contents of a table `people` is returned at
+
+.. code-block:: HTTP
+
+  GET /people
+
+There are no deeply/nested/routes. Each route provides OPTIONS, GET, POST, PATCH, and DELETE verbs depending entirely on database permissions.
+
+.. note::
+
+  Why not provide nested routes? Many APIs allow nesting to retrieve related information, such as :code:`/films/1/director`. We offer a more flexible mechanism (inspired by GraphQL) to embed related information. It can handle one-to-many and many-to-many relationships. This is covered in the section about Embedding.
+
+Filtering
+---------
+
+You can filter result rows by adding conditions on columns, each condition a query string parameter. For instance, to return people aged under 13 years old:
+
+.. code-block:: http
+
+  GET /people?age=lt.13
+
+Adding multiple parameters conjoins the conditions:
+
+.. code-block:: http
+
+  GET /people?age=gte.18&student=is.true
+
+These operators are available:
+
+============  =============================================
+abbreviation  meaning
+============  =============================================
+eq            equals
+gte           greater than or equal
+gt            greater than
+lte           less than or equal
+lt            less than
+neq           not equal
+like          LIKE operator (use * in place of %)
+ilike         ILIKE operator (use * in place of %)
+in            one of a list of values e.g. :code:`?a=in.1,2,3`
+is            checking for exact equality (null,true,false)
+@@            full-text search using to_tsquery
+@>            contains e.g. :code:`?tags=@>.{example, new}`
+<@            contained in e.g. :code:`?values=<@{1,2,3}`
+not           negates another operator, see below
+============  =============================================
+
+
+To negate any operator, prefix it with :code:`not` like :code:`?a=not.eq.2`.
+
+For more complicated filters (such as those involving condition 1 OR condition 2) you will have to create a new view in the database.
+
+.. _computed_cols:
+
+Computed Columns
+~~~~~~~~~~~~~~~~
+
+Filters may be applied to computed columns as well as actual table/view columns, even though the computed columns will not appear in the output. For example, to search first and last names at once we can create a computed column that will not appear in the output but can be used in a filter:
+
+.. code-block:: sql
+
+  CREATE TABLE people (
+    fname text,
+    lname text
+  );
+
+  CREATE FUNCTION full_name(people) RETURNS text AS $$
+    SELECT $1.fname || ' ' || $1.lname;
+  $$ LANGUAGE SQL;
+
+  # (optional) add an index to speed up anticipated query
+  CREATE INDEX people_full_name_idx ON people
+    USING GIN (to_tsvector('english', fname || ' ' || lname));
+
+A full-text search on the computed column:
+
+.. code-block:: http
+
+  GET /people?full_name=@@.Beckett
+
+Ordering
+--------
+
+The reserved word :code:`order` reorders the response rows. It uses a comma-separated list of columns and directions:
+
+.. code-block:: http
+
+  GET /people?order=age.desc,height.asc
+
+If no direction is specified it defaults to ascending order:
+
+.. code-block:: http
+
+  GET /people?order=age
+
+If you care where nulls are sorted, add nullsfirst or nullslast:
+
+.. code-block:: http
+
+  GET /people?order=age.nullsfirst
+  GET /people?order=age.desc.nullslast
+
+To order the embedded items, you need to specify the tree path for the order param like so.
+
+.. code-block:: http
+
+  GET /projects?select=id,name,tasks{id,name}&order=id.asc&tasks.order=name.asc
+
+You can also use :ref:`computed_cols` to order the results, even though the computed columns will not appear in the output.
+
+Limits and Pagination
+---------------------
+
+Counting
+--------
+
+Response Format
+---------------
+
+Singular or Plural
+------------------
+
+OpenAPI Support
+===============
+
+Resource Embedding
+==================
+
+Query Limitations
+=================
+
+Stored Procedures
+=================
+
+Insertions / Updates
+====================
+
+Getting Results
+---------------
+
+Bulk Insert
+-----------
+
+Deletions
+=========

index.rst

@@ -13,26 +13,11 @@
 
    install.rst
 
-.. Installation
+.. toctree::
-..   Binary Release
+   :caption: API
-..   Build from Source
+
-..   Docker
+   api.rst
-.. API
+
-..   Tables and Views
-..     Filtering
-..     Ordering
-..     Limits and Pagination
-..     Counting
-..     Response Format
-..     Singular or Plural
-..   OpenAPI Support
-..   Resource Embedding
-..   Query Limitations
-..   Stored Procedures
-..   Insertions / Updates
-..     Getting Results
-..     Bulk Insert
-..   Deletions
 .. Authentication
 ..   Overview of Role System
 ..   JSON Web Tokens