From e8ab260f3152d5d478912440e69d7903fe813a2c Mon Sep 17 00:00:00 2001
From: Michael DeHaan <michael.dehaan@gmail.com>
Date: Tue, 17 Jun 2014 13:52:27 -0500
Subject: Start of guidelines around API development.

---
 API_STANDARDS.md | 85 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 85 insertions(+)
 create mode 100644 API_STANDARDS.md

(limited to 'API_STANDARDS.md')

diff --git a/API_STANDARDS.md b/API_STANDARDS.md
new file mode 100644
index 0000000000..469fef585d
--- /dev/null
+++ b/API_STANDARDS.md
@@ -0,0 +1,85 @@
+Coding Standards and Practices
+==============================
+
+This is not meant to be a style document so much as a practices document for ensuring performance and convention in the Ansible Tower API.
+
+Paginate Everything
+===================
+
+Anything that returns a collection must be paginated.
+
+Assume large data sets
+======================
+
+Don't test exclusively with small data.  Assume 1000-10000 hosts in all operations, with years of event data.
+
+Some of our users have 30,000 machines they manage.
+
+API performance
+===============
+
+In general, the expected response time for any API call is something like 1/4 of a second or less.  Signs of slow API
+performance should be regularly checked, particularly for missing indexes.
+
+Missing Indexes
+===============
+
+Any filters the UI uses should be indexed.
+
+Migrations
+==========
+
+Always think about any existing data when adding any new fields.  It's ok to wait in upgrade time to get the database to be 
+consistent.
+
+Limit Queries
+=============
+
+The number of queries made should be constant time and must not vary with the size of the result set.
+
+Consider RBAC
+=============
+
+The returns of all collections must be filtered by who has access to view them, without exception
+
+Discoverability
+===============
+
+All API endpoints must be able to be traversed from "/", and have comments, where possible, explaining their purpose
+
+Friendly Comments
+=================
+
+All API comments are exposed by the API browser and must be fit for customers.   Avoid jokes in API comments and error
+messages, as well as FIXME comments in places that the API will display.
+
+UI Sanity
+=========
+
+Where possible the API should provide API endpoints that feed raw data into the UI, the UI should not have to do lots of
+data transformations, as it is going to be less responsive and able to do these things.
+
+When requiring a collection of times of size N, the UI must not make any extra API queries for each item in the result set
+
+Effective Usage of Query Sets
+=============================
+
+The system must return Django result sets rather than building JSON in memory in nearly all cases.  Use things like
+exclude and joins, and let the database do the work.
+
+Serializers
+===========
+
+No database queries may be made in serializers because these are executed once per item, rather than paginated.
+
+REST verbs
+==========
+
+REST verbs should be RESTy.  Don't use GETs to do things that should be a PUT or POST.
+
+Unit tests
+==========
+
+Every URL/route must have unit test coverage.  Consider both positive and negative tests.
+
+
-- 
cgit v1.2.3