RestfulApi

Full CRUD operations for a model.

  1. Overview
  2. model_class
  3. writeable_column_names
  4. readable_column_names
  5. searchable_column_names
  6. sortable_column_names
  7. default_sort_column_name
  8. read_only
  9. create_endpoint
  10. delete_endpoint
  11. update_endpoint
  12. get_endpoint
  13. list_endpoint
  14. create_request_methods
  15. update_request_methods
  16. delete_request_methods
  17. get_request_methods
  18. list_request_methods
  19. id_column_name
  20. group_by_column_name
  21. input_validation_callable
  22. include_routing_data_in_request_data
  23. url
  24. default_sort_direction
  25. default_limit
  26. maximum_limit
  27. request_methods
  28. response_headers
  29. output_map
  30. output_schema
  31. column_overrides
  32. internal_casing
  33. external_casing
  34. security_headers
  35. description
  36. authentication
  37. authorization

Overview

This endpoint group sets up all five standard endpoints to manage a model:

  1. Create
  2. Update
  3. Delete
  4. Get
  5. List

As such, you can set any option for all of the above endpoints. All five endpoints are enabled by default but can be turned off individually. It’s important to understand that the actual API behavior is controlled by other endoints. This endpoint group creates them and routes requests to them. So, to fully understand the behavior of the subsequent Restful API, you have to consult the documentation for the endpoints themselves.

For routing purposes, the create and list endpoints are reachable via the URL specified for this endpoint group and are separated by request method (POST for create by default, GET for list). The update, delete, and get endoints all expect the id to be appended to the base URL, and then are separated by request method (PATCH for update, DELETE for delete, and GET for get). See the example app and calls below:

import clearskies
from clearskies.validators import Required, Unique
from clearskies import columns


class User(clearskies.Model):
    id_column_name = "id"
    backend = clearskies.backends.MemoryBackend()

    id = columns.Uuid()
    name = columns.String(validators=[Required()])
    username = columns.String(
        validators=[
            Required(),
            Unique(),
        ]
    )
    age = columns.Integer(validators=[Required()])
    created_at = columns.Created()
    updated_at = columns.Updated()


wsgi = clearskies.contexts.WsgiRef(
    clearskies.endpoints.RestfulApi(
        url="users",
        model_class=User,
        readable_column_names=["id", "name", "username", "age", "created_at", "updated_at"],
        writeable_column_names=["name", "username", "age"],
        sortable_column_names=["id", "name", "username", "age", "created_at", "updated_at"],
        searchable_column_names=["id", "name", "username", "age", "created_at", "updated_at"],
        default_sort_column_name="name",
    )
)
wsgi()

Which spins up a fully functional API. In the below usage examples we create two users, fetch one of them, update a user, delete the other, and then list all users.

$ curl 'http://localhost:8080/users' -d '{"name":"Bob", "username": "bob", "age": 25}' | jq
{
    "status": "success",
    "error": "",
    "data": {
        "id": "8bd9c03f-bb0c-41bd-afbc-f9526ded88f4",
        "name": "Bob",
        "username": "bob",
        "age": 25,
        "created_at": "2025-06-10T12:39:35+00:00",
        "updated_at": "2025-06-10T12:39:35+00:00"
    },
    "pagination": {},
    "input_errors": {}
}

$ curl 'http://localhost:8080/users' -d '{"name":"Alice", "username": "alice", "age": 22}' | jq
{
    "status": "success",
    "error": "",
    "data": {
        "id": "16d483c6-0eb1-4104-b07b-32f3d736223f",
        "name": "Alice",
        "username": "alice",
        "age": 22,
        "created_at": "2025-06-10T12:42:59+00:00",
        "updated_at": "2025-06-10T12:42:59+00:00"
    },
    "pagination": {},
    "input_errors": {}
}

$ curl 'http://localhost:8080/users/8bd9c03f-bb0c-41bd-afbc-f9526ded88f4' | jq
{
    "status": "success",
    "error": "",
    "data": {
        "id": "8bd9c03f-bb0c-41bd-afbc-f9526ded88f4",
        "name": "Bob",
        "username": "bob",
        "age": 25,
        "created_at": "2025-06-10T12:39:35+00:00",
        "updated_at": "2025-06-10T12:39:35+00:00"
    },
    "pagination": {},
    "input_errors": {}
}

$ curl 'http://localhost:8080/users/16d483c6-0eb1-4104-b07b-32f3d736223f' -d '{"name":"Alice Smith", "age": 23}' -X PATCH | jq
{
    "status": "success",
    "error": "",
    "data": {
        "id": "16d483c6-0eb1-4104-b07b-32f3d736223f",
        "name": "Alice Smith",
        "username": "alice",
        "age": 23,
        "created_at": "2025-06-10T12:42:59+00:00",
        "updated_at": "2025-06-10T12:45:01+00:00"
    },
    "pagination": {},
    "input_errors": {}
}

$ curl 'http://localhost:8080/users/8bd9c03f-bb0c-41bd-afbc-f9526ded88f4' -X DELETE | jq
{
    "status": "success",
    "error": "",
    "data": {},
    "pagination": {},
    "input_errors": {}
}

$ curl 'http://localhost:8080/users/' | jq
{
    "status": "success",
    "error": "",
    "data": [
        {
        "id": "16d483c6-0eb1-4104-b07b-32f3d736223f",
        "name": "Alice Smith",
        "username": "alice",
        "age": 23,
        "created_at": "2025-06-10T12:42:59+00:00",
        "updated_at": "2025-06-10T12:45:01+00:00"
        }
    ],
    "pagination": {
        "number_results": 1,
        "limit": 50,
        "next_page": {}
    },
    "input_errors": {}
}

model_class

Required

writeable_column_names

Required

readable_column_names

Required

searchable_column_names

Required

sortable_column_names

Required

default_sort_column_name

Required

read_only

Optional

create_endpoint

Optional

The endpoint class to use for managing the create operation.

This defaults to clearskies.endpoints.Create. To disable the create operation all together, set this to None.

delete_endpoint

Optional

The endpoint class to use for managing the delete operation.

This defaults to clearskies.endpoints.Delete. To disable the delete operation all together, set this to None.

update_endpoint

Optional

The endpoint class to use for managing the update operation.

This defaults to clearskies.endpoints.Update. To disable the update operation all together, set this to None.

get_endpoint

Optional

The endpoint class to use to fetch individual records.

This defaults to clearskies.endpoints.Get. To disable the get operation all together, set this to None.

list_endpoint

Optional

The endpoint class to use to list records.

This defaults to clearskies.endpoints.SimpleSearch. To disable the list operation all together, set this to None.

create_request_methods

Optional

The request method(s) to use to route to the create operation. Default is [“POST”].

update_request_methods

Optional

The request method(s) to use to route to the update operation. Default is [“PATCH”].

delete_request_methods

Optional

The request method(s) to use to route to the delete operation. Default is [“DELETE”].

get_request_methods

Optional

The request method(s) to use to route to the get operation. Default is [“GET”].

list_request_methods

Optional

The request method(s) to use to route to the create operation. Default is [“GET”].

id_column_name

Optional

The request method(s) to use to route to the create operation. Default is [“POST”].

group_by_column_name

Optional

input_validation_callable

Optional

include_routing_data_in_request_data

Optional

url

Optional

The base URL to be used for all the endpoints.

default_sort_direction

Optional

default_limit

Optional

maximum_limit

Optional

request_methods

Optional

response_headers

Optional

output_map

Optional

output_schema

Optional

column_overrides

Optional

internal_casing

Optional

“snake_case”

external_casing

Optional

security_headers

Optional

description

Optional

authentication

Optional

authorization

Optional