ModelViewSet APIs

CRUD APIs in the Spear backend are often handled using Django's built in ModelViewSet. APIs built this way share methods and behavior, and are documented once here.

For example, /client/ is an API built using ModelViewSet. With this API you may:

• GET /client/ to retrieve a paginated list of items
• POST /client/ to create a new client
• GET /client/1 to get the client with id=1
• PUT /client/1 to completely overwrite the data for the client with id=1
• PATCH /client/1 to partially update provided fields for the client with id=1
• DELETE /client/1 to delete the client with id=1

Examples are provided below for the /client endpoint, but these APIs will apply for all APIs built using ModelViewSet.

Such APIs will be documented by providing examples of JSON objects for the model and all its fields, which can then be manipulated using the APIs below.

List Items

GET /client/: Lists all clients.

Depending on the model, you may have the option to specify a query/filter along with other options.

Pagination

All list endpoints are paginated using the PaginationClass. The response includes pagination metadata along with the results.

Pagination Parameters:

• limit: Number of items per page (default: 20, max: 300)
• page: Page number to retrieve (default: 1)

Example:

• GET /client/ - Returns first 20 items
• GET /client/?limit=50 - Returns first 50 items
• GET /client/?limit=10&page=2 - Returns items 11-20

Example Response

{
    "results": [
        {
            "id": 1,
            "name": "Test Client",
            "is_active": true,
            "is_prospective_client": false
        },
        {
            "id": 2,
            "name": "Test 2",
            "is_active": true,
            "is_prospective_client": false
        }
    ],
    "count": 2,
    "limit": 20,
    "page": 1
}

Response Fields:

• results: Array of items for the current page
• count: Total number of items across all pages
• limit: Number of items per page for this request
• page: Current page number

Create Item

POST /client/: Creates a new client.

Example Request

Request Headers

Content-Type: application/json

Request Body

{
    "name": "Sarina",
    "is_active": true,
    "is_prospective_client": true
}

Response

{
    "id": 1,
    "name": "Sarina",
    "is_active": true,
    "is_prospective_client": true
}

Get Item

GET /client/1: Retrieves the client with id=1

Example Response

{
    "id": 1,
    "name": "Test Client",
    "is_active": true,
    "is_prospective_client": false
}

Partially Update Item

PATCH /client/1: Updates the provided fields for client id=1.

Example Request

Request Headers

Content-Type: application/json

Request Body

{
    "is_active": false
}

Response

{
    "id": 1,
    "name": "Sarina",
    "is_active": false,
    "is_prospective_client": true
}

Update Item

PUT /client/1: Replaces data for client id=1 with the data provided. Unspecified fields will use their default value if available. You may want to use a partial update instead if you only need to change one or a few fields.

Example Request

Request Headers

Content-Type: application/json

Request Body

{
    "name": "Sarina (Black Sunny)",
    "is_active": false,
    "is_prospective_client": false
}

Response

{
    "id": 1,
    "name": "Sarina (Black Sunny)",
    "is_active": false,
    "is_prospective_client": false
}

Delete Item

DELETE /client/1: Deletes the client with id=1

No request body is needed. Upon success, you will receive a 204 No Content response.