API

Apps

Meta information about the Integreat CMS API app

class integreat_cms.api.apps.ApiConfig(app_name, app_module)[source]

Bases: AppConfig

Configuration parameters for the API app

__init__(app_name, app_module)[source]
classmethod create(entry)[source]

Factory that creates an app config from an entry in INSTALLED_APPS.

default_auto_field[source]
get_model(model_name, require_ready=True)[source]

Return the model with the given case-insensitive model_name.

Raise LookupError if no model exists with this name.

get_models(include_auto_created=False, include_swapped=False)[source]

Return an iterable of models.

By default, the following models aren’t included:

  • auto-created models for many-to-many relations without an explicit intermediate table,

  • models that have been swapped out.

Set the corresponding keyword argument to True to include such models. Keyword arguments aren’t documented; they’re a private API.

import_models()[source]
name: Final[str] = 'integreat_cms.api'[source]

Full Python path to the application

ready()[source]

Override this method in subclasses to run code when Django starts.

verbose_name: Final[Promise] = 'API'[source]

Human-readable name for the application

Decorators

This module includes functions that are used as decorators in the API endpoints.

integreat_cms.api.decorators.api_token_required(permission: str | None = None) → Callable[source]

This decorator can be used to restrict an API endpoint to requests which carry a valid personal API token of a CMS user (Authorization: Bearer <token>).

The request is executed on behalf of the token’s user, so the endpoint inherits exactly the permissions of that user instead of bypassing the RBAC structure.

Note that this only checks the global permission — it does not verify that the user is a member of the region in the URL. Region-scoped endpoints have to check request.region against the user’s regions themselves, analogous to region_permission_required().

Parameters:

permission (str | None) – The permission the token’s user must hold, e.g. cms.change_region

Returns:

The decorator for the API view function

Return type:

Callable

integreat_cms.api.decorators.feedback_handler(func: Callable) → Callable[source]

Decorator definition for feedback API functions and methods

Parameters:

func (Callable) – decorated function

Returns:

The decorated feedback view function

Return type:

Callable

integreat_cms.api.decorators.get_client_ip(request: HttpRequest) → str | None[source]

Get remote IP address. If a trusted IP header is configured but not set, return None.

Parameters:

request (HttpRequest) – Django request

Returns:

source IPv4/IPv6 address of the request

Return type:

str | None

integreat_cms.api.decorators.json_response(function: Callable) → Callable[source]

This decorator can be used to catch Http404 exceptions and convert them to a JsonResponse. Without this decorator, the exceptions would be converted to HttpResponse.

Parameters:

function (Callable) – The view function which should always return JSON

Returns:

The decorated function

Return type:

Callable

integreat_cms.api.decorators.matomo_tracking(func: Callable) → Callable[source]

This decorator is supposed to be applied to API content endpoints. It will track the request in Matomo. The request to the Matomo API is executed asynchronously in its own thread to not block the Integreat CMS API request.

Only the URL and the User Agent will be sent to Matomo.

Parameters:

func (Callable) – decorated function

Returns:

The decorated feedback view function

Return type:

Callable

integreat_cms.api.decorators.rate_limit(func: Callable) → Callable[source]

Decorator to apply rate limiting on views.

Parameters:

func (Callable)

Return type:

Callable

integreat_cms.api.decorators.rate_limited(request: HttpRequest) → bool[source]

Check if IP is rate limited and record hit. If a trusted IP header is configured, deny access if the header is not set in the request.

Parameters:

request (HttpRequest) – Django request

Returns:

True if the IP should be rate limited

Return type:

bool

Urls

Expansion of API-Endpoints for the CMS

integreat_cms.api.urls.app_name: Final = 'api'[source]

The namespace for this URL config (see django.urls.ResolverMatch.app_name)

integreat_cms.api.urls.urlpatterns: list[URLPattern] = [<URLResolver <URLPattern list> (None:None) 'api/v3/regions/'>, <URLPattern 'api/v3/webhook/zammad/' [name='zammad_webhook']>, <URLResolver <URLPattern list> (None:None) 'wp-json/extensions/v3/sites/'>, <URLResolver <URLPattern list> (None:None) 'api/v3/social/'>, <URLResolver <URLPattern list> (None:None) 'api/v3/raw-content/'>, <URLResolver <URLPattern list> (None:None) 'api/v3/<slug:region_slug>/'>, <URLResolver <URLPattern list> (None:None) '<slug:region_slug>/'>][source]

The url patterns of this module (see URL dispatcher)

[
    <URLResolver <URLPattern list> (None:None) 'api/v3/regions/'>,
    <URLPattern 'api/v3/webhook/zammad/' [name='zammad_webhook']>,
    <URLResolver <URLPattern list> (None:None) 'wp-json/extensions/v3/sites/'>,
    <URLResolver <URLPattern list> (None:None) 'api/v3/social/'>,
    <URLResolver <URLPattern list> (None:None) 'api/v3/raw-content/'>,
    <URLResolver <URLPattern list> (None:None) 'api/v3/<slug:region_slug>/'>,
    <URLResolver <URLPattern list> (None:None) '<slug:region_slug>/'>,
]