mirror of
https://github.com/ansible/awx.git
synced 2024-11-01 08:21:15 +03:00
86 lines
2.5 KiB
Markdown
86 lines
2.5 KiB
Markdown
|
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.
|
||
|
|
|
||
|
|
|