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