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.
Anything that returns a collection must be paginated.
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.
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.
Any filters the UI uses should be indexed.
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.
The number of queries made should be constant time and must not vary with the size of the result set.
The returns of all collections must be filtered by who has access to view them, without exception
All API endpoints must be able to be traversed from "/", and have comments, where possible, explaining their purpose
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.
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
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.
No database queries may be made in serializers because these are executed once per item, rather than paginated.
REST verbs should be RESTy. Don't use GETs to do things that should be a PUT or POST.
Every URL/route must have unit test coverage. Consider both positive and negative tests.