Start of guidelines around API development.

Author: mpdehaan

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.
+
+