Fields

Field

class django_declarative_apis.machinery.attributes.RequestField(*args, **kwargs)

Endpoint properties are called fields. Fields can be simple types such as int, or they can be used as a decorator on a function.

Valid field types: A subclass of int, bool, float, str, dict, complex, pydantic.BaseModel

Example

from django_declarative_apis.machinery import field

task = field(required=True, type=str)

Parameters

• required (optional) – Determines whether the field is required for the EndpointDefinition. Defaults to False.

• name (optional) – Allows the name of the field in HTTP API to be different from its name defined on the EndpointDefinition. Defaults to None.

• type (optional) – Determines the type of the field. Type needs to be on of the valid field types listed above. Defaults to String

• default (optional) – Sets the default value for the field. Defaults to None.

• description (optional) – Describes the purpose of the field. Defaults to None.

• multivalued (optional) – Allows a field to be specified multiple times in the request. With multivalued set to True, the EndpointHandler will receive a list of values instead of a single value. Defaults to False.

Example

Request:

GET https://example.com?foo=bar1&foo=bar2

EndpointDefinition:

from django_declarative_apis.machinery import field

class FooDefinition(EndpointDefinition):
    foo = field(multivalued=True)

In the EndpointDefinition, self.foo would be equal to [‘bar1’, ‘bar2’]

Field as decorators on a function

Define fields as a decorator on a function when you want to perform operations on the data before returning it and using it in your EndpointDefinition.

The function will have @field decorator at the top. Once the type=<type> argument of @field decorator is set, that is going to be the type of the input to the field function.

Example: Let’s say the only acceptable status for a task in todo list is True

@field(
     required=False,
     name='completion_status',
     type=bool,
     default=None,
     description='Status for a task in the todo list. The only valid status is "True"')
 def status(self, raw_value):
    if status.get(raw_value, None) != True:
         raise ValueError(f"{raw_value} is not a valid status")
    return True

URL Field

class django_declarative_apis.machinery.attributes.RequestUrlField(*args, **kwargs)

A specialized type of field that takes any parameter that directly appears in the URL path.

Parameters

name (optional) – Allows the name of the field in HTTP API to be different from its name defined on the EndpointDefinition. Defaults to None

Example: URL defined in urls.py

url_patterns = [
    url(
        r"^tasks/(?P<id>{0})/$".format(r"[0-9]{1}"),
        handlers.TodoDetailEndpoint,
        )
]

url_field is used to extract the id of a single task from the above URL for deleting that task.

from django_declarative_apis.machinery import url_field

class TodoDeleteSingleTaskDefinition(
    TodoResourceMixin,
    machinery.ResourceEndpointDefinition,
):
    resource_id = url_field(name='id')

    @endpoint_resource(type=Todo)
    def resource(self):
        task = Todo.objects.delete(id=self.resource_id)
        return django.http.HttpResponse(status=http.HTTPStatus.OK)

Operations on Fields

class django_declarative_apis.machinery.attributes.RequireOneAttribute(*component_field_getters, **kwargs)

Exactly one of the given fields must be present.

Example

from django_declarative_apis.machinery import require_one

sample_field_1 = field()
sample_field_2 = field()

sample_require_one = require_one(
        sample_field_1,
        sample_field_2,
    )

class django_declarative_apis.machinery.attributes.RequireAllAttribute(*component_field_getters, **kwargs)

All fields must be populated.

class django_declarative_apis.machinery.attributes.RequireAllIfAnyAttribute(*component_field_getters, **kwargs)

Either all fields must be present or all fields must be missing.