API resources
This file handles the CRUD operations.
When you create a new API called Swords
, the resource
name is Sword
and the file name is SwordResource
. The endpoint for CRUD operations are:
Action | HTTP method | Endpoint |
---|---|---|
Create | POST | /swords |
List | GET | /swords |
Detail | GET | /swords/:id |
Update | PUT | /swords/:id |
Delete | DELETE | /swords/:id |
If your resource belongs to a parent model, for example a sword belongs to a team, then your
endpoints will be the following (note that swords for the create and list endpoints are nested
under the teams
resource:
Action | HTTP method | Endpoint |
---|---|---|
Create | POST | /teams/:id/swords |
List | GET | /teams/:id/swords |
Detail | GET | /swords/:id |
Update | PUT | /swords/:id |
Delete | DELETE | /swords/:id |
Collection
This method is executed when you make a request for a list of a specific resource.
Example: GET /swords
.
Create a file called SwordResource
that is a subclass of 1 of the following:
GenericResource
: subclass this class if you want to execute arbitrary codeDatabaseResource
: subclass this class only if your resource is directly associated to a database model. This subclass has many methods defined by default that handles CRUD operations automatically.
Creating a subclass of GenericResource
Create a file called backend/api/resources/SwordResource.py
:
Creating a subclass of DatabaseResource
Here is how we would get a list of swords that are weak and belong to team ID 1:
Create
This method is executed when you make a request to create a new instance of a resource.
Example: POST /swords
.
GenericResource
DatabaseResource
You typically never have to override the create
class method. The instances where it is overrided
include a scenario when you want to execute a callback function only if the resource was
successfully created.
The DatabaseResource
create
method will take the keys and values in the payload argument, assign
those values to a newly instantiated Sword
object, and then save the model to the database.
Member
This method is executed when you make a fetch a single resource using it’s ID.
Example: GET /swords/:id
.
GenericResource
DatabaseResource
You almost never have to override the member
method.
If you do, see TrainingRunResource
for an example.
Update
This method is executed when you want to update a single resource using it’s ID.
Example: PUT /swords/:id
.
This is almost the same as the create
method except it’s an instance method and the ID of the
resource you want to update must be included in the URL.
DatabaseResource
You almost never have to override the update
method.
If you do, see ModelVersionResource
for an example.
Delete
This method is executed when you want to delete a single resource using it’s ID.
Example: DELETE /swords/:id
.
DatabaseResource
You almost never have to override the delete
method.
Registering parent models
If your resource belongs to a parent model, for example a sword belongs to a team, you must do the following in order for these endpoints to work properly:
- Create:
POST /teams/:id/swords
- List:
GET /teams/:id/swords
Pre-load single associated object
The sword model belongs to a user via the sword.user_id
column. If you are fetching a list of 100
swords and in your code you are accessing the methods of the user
object via sword.user
(e.g. sword.user.name
), you will inadvertently make 100 extra API calls to the users
database table. Do the following to prevent this:
Pre-load multiple associated objects
The sword has many opponents that were defeated by it. You can query all the opponents via the
swords.opponents.objects.all()
method. This will fetch all opponents from the database where
opponent.sword_id
equals sword.id
. If you are accessing the opponents of each sword when
fetching a list of 100 swords, you will be making 100 extra API calls to the opponents
database.
Do the following to prevent this: