PluginDataApi Model

class smarter.apps.plugin.models.PluginDataApi(*args, **kwargs)

Bases: PluginDataBase

Stores API-based data configuration for a Smarter plugin.

This model is used to store the connection endpoint details for a REST API remote data source. It defines the API connection, endpoint, parameters, headers, body, test values, and result limits. The model provides methods for preparing and executing API requests, as well as validating the structure of parameters, headers, and test values.

PluginDataApi is a concrete subclass of PluginDataBase and is referenced by PluginMeta to provide the data payload for API-type plugins. It is tightly integrated with ApiConnection for managing API connectivity and request execution, and supports advanced features such as parameterized endpoints, dynamic placeholder validation, and flexible request construction.

This model is responsible for:

• Storing the API endpoint path, HTTP method, parameter schema, headers, and request body.

• Validating that all placeholders in the endpoint are defined in the parameters.

• Ensuring that test values, headers, and URL parameters are provided and conform to the expected structure.

• Preparing and executing API requests with runtime parameters, including safe substitution of placeholders.

• Enforcing result limits to prevent excessive data retrieval.

• Providing methods for returning sanitized API responses for use in LLM responses.

Typical use cases include plugins that need to retrieve or send data to external REST APIs, integrate with third-party services, or expose organizational APIs to the Smarter LLM platform.

See also:

• PluginDataBase

• ApiConnection

• PluginMeta

Parameters:

• id (BigAutoField) – Primary key: ID

• created_at (DateTimeField) – Created at

• updated_at (DateTimeField) – Updated at

• description (TextField) – Description. A brief description of what this plugin returns. Be verbose, but not too verbose.

• parameters (JSONField) –

  Parameters. A JSON dict containing parameter names and data types. Example: {‘required’: [], ‘properties’: {‘max_cost’: {‘type’: ‘float’, ‘description’: ‘the maximum cost that a student is willing to pay for a course.’}, ‘description’: {‘enum’: [‘AI’, ‘mobile’, ‘web’, ‘database’, ‘network’, ‘neural networks’], ‘type’: ‘string’, ‘description’: ‘areas of specialization for courses in the catalogue.’}}}

  A JSON dict containing parameter names and data types. Example: {‘required’: [], ‘properties’: {‘max_cost’: {‘type’: ‘float’, ‘description’: ‘the maximum cost that a student is willing to pay for a course.’}, ‘description’: {‘enum’: [‘AI’, ‘mobile’, ‘web’, ‘database’, ‘network’, ‘neural networks’], ‘type’: ‘string’, ‘description’: ‘areas of specialization for courses in the catalogue.’}}}

• test_values (JSONField) –

  Test values. A JSON dict containing test values for each parameter. Example: {‘city’: ‘San Francisco’}

  A JSON dict containing test values for each parameter. Example: {‘city’: ‘San Francisco’}

• method (CharField) – Method. The HTTP method to use for the API request. Example: ‘GET’, ‘POST’.

• endpoint (CharField) – Endpoint. The endpoint path for the API. Example: ‘/v1/weather’.

• url_params (JSONField) – Url params. A JSON dict containing URL parameters. Example: {‘city’: ‘San Francisco’, ‘state’: ‘CA’}

• headers (JSONField) – Headers. A JSON dict containing headers to be sent with the API request. Example: {‘Authorization’: ‘Bearer <token>’}

• body (JSONField) – Body. A JSON dict containing the body of the API request, if applicable.

• limit (IntegerField) – Limit. The maximum number of rows to return from the API response.

Relationship fields:

Parameters:

• plugin (OneToOneField to PluginMeta) – Plugin (related name: plugin_data_base_plugin)

• plugindatabase_ptr (OneToOneField to PluginDataBase) – Primary key: Plugindatabase ptr (related name: plugindataapi)

• connection (ForeignKey to ApiConnection) – Connection. The API connection associated with this plugin. (related name: plugin_data_api_connection)

class DataTypes

Bases: object

BOOL = 'bool'

DICT = 'dict'

FLOAT = 'float'

INT = 'int'

LIST = 'list'

NULL = 'null'

STR = 'str'

classmethod all()

Return type:

list

exception DoesNotExist

Bases: DoesNotExist

exception MultipleObjectsReturned

Bases: MultipleObjectsReturned

body

JSONField

Body. A JSON dict containing the body of the API request, if applicable.

Type:

Type

connection

ForeignKey to ApiConnection

Connection. The API connection associated with this plugin. (related name: plugin_data_api_connection)

Type:

Type

connection_id

Internal field, use connection instead.

data(params=None)

Returns a dict of custom data return results.

Return type:

dict

endpoint

CharField

Endpoint. The endpoint path for the API. Example: ‘/v1/weather’.

Type:

Type

execute_request(params)

Execute the API request and return the results.

Return type:

Union[dict, bool]

classmethod get_cached_data_by_plugin(plugin, invalidate=False)

Return a single instance of PluginDataApi by plugin.

This method caches the results to improve performance.

Parameters:

plugin (PluginMeta) – The plugin whose data should be retrieved.

Returns:

A PluginDataApi instance if found, otherwise None.

Return type:

Union[PluginDataApi, None]

classmethod get_cached_object(invalidate=False, pk=None, plugin=None)

Retrieve a model instance by primary key, using caching to optimize performance. This method is selectively overridden in models that inherit from MetaDataModel to provide class-specific function parameters.

Example usage:

# Retrieve by primary key
instance = MyModel.get_cached_object(pk=1)

Parameters:

• invalidate (bool) – If True, invalidate the cache for this query before retrieving the object.

• pk (int) – The primary key of the model instance to retrieve.

• plugin (PluginMeta) – The PluginMeta instance associated with the data to retrieve.

Returns:

The model instance if found, otherwise None.

Return type:

Optional[“PluginDataBase”]

get_method_display(*, field=<django.db.models.CharField: method>)

Shows the label of the method. See get_FOO_display() for more information.

headers

JSONField

Headers. A JSON dict containing headers to be sent with the API request. Example: {‘Authorization’: ‘Bearer <token>’}

Type:

Type

limit

IntegerField

Limit. The maximum number of rows to return from the API response.

Type:

Type

method

CharField

Method. The HTTP method to use for the API request. Example: ‘GET’, ‘POST’.

Choices:

• GET

• POST

• PUT

• DELETE

Type:

Type

plugindatabase_ptr

OneToOneField to PluginDataBase

Primary key: Plugindatabase ptr (related name: plugindataapi)

Type:

Type

plugindatabase_ptr_id

Internal field, use plugindatabase_ptr instead.

prepare_request(params)

Prepare the API request by merging parameters, headers, and body.

Return type:

dict

sanitized_return_data(params=None)

Return a dict by executing the API request with the provided params.

Return type:

Union[dict, bool]

save(*args, **kwargs)

Override the save method to validate the field dicts.

test()

Test the API request using the test_values in the record.

Return type:

Union[dict, bool]

property url: str

Return the full URL for the API endpoint.

url_params

JSONField

Url params. A JSON dict containing URL parameters. Example: {‘city’: ‘San Francisco’, ‘state’: ‘CA’}

Type:

Type

validate()

Validate the model.

Attention

Intended to be overridden in subclasses to provide custom validation logic.

Return type:

bool

validate_all_placeholders_in_parameters()

Validate that all placeholders in the SQL query string are present in the parameters.

Return type:

None

validate_body()

Validate the body format. Currently nothing to do here.

Return type:

None

validate_endpoint()

Validate the endpoint format.

Return type:

None

validate_headers()

Validate the headers format.

Return type:

None

validate_test_values()

Validate the test values format.

Return type:

None

validate_url_params()

Validate the URL parameters format.

Return type:

None