Configuration¶
Generally Eve configuration is best done with configuration files. The configuration files themselves are actual Python files.
Configuration with Files¶
On startup, Eve will look for a settings.py file in the application folder. You can choose an alternative filename/path. Just pass it as an argument when you instantiate the application.
from eve import Eve
app = Eve(settings='my_settings.py')
app.run()
Configuration with a Dictionary¶
Alternatively, you can choose to provide a settings dictionary:
my_settings = {
'MONGO_HOST': 'localhost',
'MONGO_PORT': 27017,
'MONGO_DBNAME': 'the_db_name'
'DOMAIN': {'contacts': {}}
}
from eve import Eve
app = Eve(settings=my_settings)
app.run()
Development / Production¶
Most applications need more than one configuration. There should be at least separate configurations for the production server and the one used during development. The easiest way to handle this is to use a default configuration that is always loaded and part of the version control, and a separate configuration that overrides the values as necessary.
This is the main reason why you can override or extend the settings with the
contents of the file the EVE_SETTINGS
environment variable points to.
The development/local settings could be stored in settings.py and then, in
production, you could export EVE_SETTINGS=/path/to/production_setting.py, and
you are done.
There are many alternative ways to handle development/production however. Using Python modules for configuration is very convenient, as they allow for all kinds of nice tricks, like being able to seamlessly launch the same API on both local and production systems, connecting to the appropriate database instance as needed. Consider the following example, taken directly from the Live demo:
# We want to run seamlessly our API both locally and on Heroku, so:
if os.environ.get('PORT'):
# We're hosted on Heroku! Use the MongoHQ sandbox as our backend.
MONGO_HOST = 'alex.mongohq.com'
MONGO_PORT = 10047
MONGO_USERNAME = '<user>'
MONGO_PASSWORD = '<pw>'
MONGO_DBNAME = '<dbname>'
else:
# Running on local machine. Let's just use the local mongod instance.
# Please note that MONGO_HOST and MONGO_PORT could very well be left
# out as they already default to a bare bones local 'mongod' instance.
MONGO_HOST = 'localhost'
MONGO_PORT = 27017
MONGO_USERNAME = 'user'
MONGO_PASSWORD = 'user'
MONGO_DBNAME = 'apitest'
Global Configuration¶
Besides defining the general API behavior, most global configuration settings are used to define the standard endpoint ruleset, and can be fine-tuned later, when configuring individual endpoints. Global configuration settings are always uppercase.
URL_PREFIX |
URL prefix for all API endpoints. Will be
used in conjunction with API_VERSION to
build API endpoints (e.g., api will be
rendered to /api/<endpoint> ). Defaults
to '' . |
API_VERSION |
API version. Will be used in conjunction with
URL_PREFIX to build API endpoints
(e.g., v1 will be rendered to
/v1/<endpoint> ). Defaults to '' . |
ALLOWED_FILTERS |
List of fields on which filtering is allowed.
Can be set to Please note: If API scraping or DB DoS attacks are a concern, then globally disabling filters and whitelisting valid ones at the local level is the way to go. |
SORTING |
True if sorting is supported for GET
requests, otherwise False . Can be
overridden by resource settings. Defaults
to True . |
PAGINATION |
True if pagination is enabled for GET
requests, otherwise False . Can be
overridden by resource settings. Defaults
to True . |
PAGINATION_LIMIT |
Maximum value allowed for QUERY_MAX_RESULTS query parameter. Values exceeding the limit will be silently replaced with this value. You want to aim for a reasonable compromise between performance and transfer size. Defaults to 50. |
PAGINATION_DEFAULT |
Default value for QUERY_MAX_RESULTS. Defaults to 25. |
QUERY_WHERE |
Key for the filters query parameter. Defaults to where . |
QUERY_SORT |
Key for the sort query parameter. Defaults to sort . |
QUERY_PROJECTION |
Key for the projections query parameter. Defaults to projection . |
QUERY_PAGE |
Key for the pages query parameter. Defaults to page . |
QUERY_MAX_RESULTS |
Key for the max results query parameter. Defaults to max_results . |
QUERY_EMBEDDED |
Key for the embedding query parameter. Defaults to embedded . |
DATE_FORMAT |
A Python date format used to parse and render
datetime values. When serving requests,
matching JSON strings will be parsed and
stored as datetime values. In
responses, datetime values will be
rendered as JSON strings using this format.
Defaults to the RFC1123 (ex RFC 822)
standard a, %d %b %Y %H:%M:%S GMT
(“Tue, 02 Apr 2013 10:29:13 GMT”). |
RESOURCE_METHODS |
A list of HTTP methods supported at resource
endpoints. Allowed values: GET ,
POST , DELETE . POST is used for
insertions. DELETE will delete all
resource contents (enable with caution).
Can be overridden by resource settings.
Defaults to ['GET'] . |
PUBLIC_METHODS |
A list of HTTP methods supported at resource
endpoints, open to public access even when
Authentication and Authorization is enabled. Can be overridden
by resource settings. Defaults to [] . |
ITEM_METHODS |
A list of HTTP methods supported at item
endpoints. Allowed values: GET ,
PATCH and DELETE . PATCH or, for
clients not supporting PATCH, POST with
the X-HTTP-Method-Override header tag,
is used for item updates; DELETE for
item deletion. Can be overridden by
resource settings. Defaults to ['GET'] . |
PUBLIC_ITEM_METHODS |
A list of HTTP methods supported at item
endpoints, left open to public access when
when Authentication and Authorization is enabled. Can be
overridden by resource settings. Defaults
to [] . |
ALLOWED_ROLES |
A list of allowed roles for resource
endpoints. Can be overridden by resource
settings. See Authentication and Authorization for more
information. Defaults to [] . |
ALLOWED_READ_ROLES |
A list of allowed roles for resource
endpoints with GET and OPTIONS methods.
Can be overridden by resource
settings. See Authentication and Authorization for more
information. Defaults to [] . |
ALLOWED_WRITE_ROLES |
A list of allowed roles for resource
endpoints with POST, PUT and DELETE
methods. Can be overridden by resource
settings. See Authentication and Authorization for more
information. Defaults to [] . |
ALLOWED_ITEM_ROLES |
A list of allowed roles for item endpoints.
See Authentication and Authorization for more information. Can
be overridden by resource settings.
Defaults to [] . |
ALLOWED_ITEM_READ_ROLES |
A list of allowed roles for item endpoints
with GET and OPTIONS methods.
See Authentication and Authorization for more information. Can
be overridden by resource settings.
Defaults to [] . |
ALLOWED_ITEM_WRITE_ROLES |
A list of allowed roles for item endpoints
with PUT, PATCH and DELETE methods.
See Authentication and Authorization for more information. Can
be overridden by resource settings.
Defaults to [] . |
CACHE_CONTROL |
Value of the Cache-Control header field
used when serving GET requests (e.g.,
max-age=20,must-revalidate ). Leave
empty if you don’t want to include cache
directives with API responses. Can be
overridden by resource settings. Defaults
to '' . |
CACHE_EXPIRES |
Value (in seconds) of the Expires header
field used when serving GET requests.
If set to a non-zero value, the header will
always be included, regardless of the
setting of CACHE_CONTROL . Can be
overridden by resource settings. Defaults
to 0. |
X_DOMAINS |
CORS (Cross-Origin Resource Sharing) support.
Allows API maintainers to specify which
domains are allowed to perform CORS
requests. Allowed values are: None ,
a list of domains or '*' for a wide-open
API. Defaults to None . |
X_HEADERS |
CORS (Cross-Origin Resource Sharing) support.
Allows API maintainers to specify which
headers are allowed to be sent with CORS
requests. Allowed values are: None or
a list of headers names. Defaults to
None . |
X_EXPOSE_HEADERS |
CORS (Cross-Origin Resource Sharing) support.
Allows API maintainers to specify which
headers are exposed within a CORS response.
Allowed values are: None or
a list of headers names. Defaults to
None . |
X_MAX_AGE |
CORS (Cross-Origin Resource Sharing) support. Allows to set max age for the access control allow header. Defaults to 21600. |
LAST_UPDATED |
Name of the field used to record a document’s
last update date. This field is
automatically handled by Eve. Defaults to
_updated . |
DATE_CREATED |
Name for the field used to record a document
creation date. This field is automatically
handled by Eve. Defaults to _created . |
ID_FIELD |
Name of the field used to uniquely identify
resource items within the database. You
want this field to be properly indexed on
the database. Defaults to _id . |
ITEM_LOOKUP |
True if item endpoints should be generally
available across the API, False
otherwise. Can be overridden by resource
settings. Defaults to True . |
ITEM_LOOKUP_FIELD |
Document field used when looking up a resource
item. Can be overridden by resource
settings. Defaults to ID_FIELD . |
ITEM_URL |
URL rule used to construct default item
endpoint URLs. Can be overridden by
resource settings. Defaults
regex("[a-f0-9]{24}") which is MongoDB
standard Object_Id format. |
ITEM_TITLE |
Title to be used when building item references, both in XML and JSON responses. Defaults to resource name, with the plural ‘s’ stripped if present. Can and most likely will be overridden when configuring single resource endpoints. |
AUTH_FIELD |
Enables User-Restricted Resource Access. When the
feature is enabled, users can only
read/update/delete resource items created
by themselves. The keyword contains the
actual name of the field used to store the
id of the user who created the resource
item. Can be overridden by resource
settings. Defaults to None , which
disables the feature. |
ALLOW_UNKNOWN |
When True , this option will allow insertion
of arbitrary, unknown fields to any API
endpoint. Use with caution. See
Allowing the Unknown for more information.
Defaults to False . |
PROJECTION |
When True , this option enables the
Projections feature. Can be
overridden by resource settings. Defaults
to True . |
EMBEDDING |
When True , this option enables the
Embedded Resource Serialization feature. Defaults to
True . |
BANDWIDTH_SAVER |
When True , POST, PUT, and PATCH responses
only return automatically handled fields
and EXTRA_RESPONSE_FIELDS . When
False , the entire document will be
sent. Defaults to True . |
EXTRA_RESPONSE_FIELDS |
Allows to configure a list of additional
document fields that should be provided
with every POST response. Normally only
automatically handled fields (ID_FIELD ,
LAST_UPDATED , DATE_CREATED ,
ETAG ) are included in response
payloads. Can be overridden by resource
settings. Defaults to [] , effectively
disabling the feature. |
RATE_LIMIT_GET |
A tuple expressing the rate limit on GET
requests. The first element of the tuple is
the number of requests allowed, while the
second is the time window in seconds. For
example, (300, 60 * 15) would set
a limit of 300 requests every 15 minutes.
Defaults to None . |
RATE_LIMIT_POST |
A tuple expressing the rate limit on POST
requests. The first element of the tuple is
the number of requests allowed, while the
second is the time window in seconds. For
example (300, 60 * 15) would set
a limit of 300 requests every 15 minutes.
Defaults to None . |
RATE_LIMIT_PATCH |
A tuple expressing the rate limit on PATCH
requests. The first element of the tuple is
the number of requests allowed, while the
second is the time window in seconds. For
example (300, 60 * 15) would set
a limit of 300 requests every 15 minutes.
Defaults to None . |
RATE_LIMIT_DELETE |
A tuple expressing the rate limit on DELETE
requests. The first element of the tuple is
the number of requests allowed, while the
second is the time window in seconds. For
example (300, 60 * 15) would set
a limit of 300 requests every 15 minutes. Defaults to
None . |
DEBUG |
True to enable Debug Mode, False
otherwise. |
ERROR |
Allows to customize the error_code field. Defaults
to _error . |
HATEOAS |
When False , this option disables
HATEOAS. Defaults to True . |
ISSUES |
Allows to customize the issues field. Defaults
to _issues . |
STATUS |
Allows to customize the status field. Defaults
to _status . |
STATUS_OK |
Status message returned when data validation is
successful. Defaults to OK . |
STATUS_ERR |
Status message returned when data validation
failed. Defaults to ERR . |
ITEMS |
Allows to customize the items field. Defaults
to _items . |
META |
Allows to customize the meta field. Defaults
to _meta |
LINKS |
Allows to customize the links field. Defaults
to _links . |
ETAG |
Allows to customize the etag field. Defaults
to _etag . |
IF_MATCH |
True to enable concurrency control, False
otherwise. Defaults to True . See
Data Integrity and Concurrency Control. |
XML |
True to enable XML support, False
otherwise. See JSON and XML Rendering. Defaults to
True . |
JSON |
True to enable JSON support, False
otherwise. See JSON and XML Rendering. Defaults to
True . |
JSON_SORT_KEYS |
True to enable JSON key sorting, False
otherwise. Defaults to False . |
VALIDATION_ERROR_STATUS |
The HTTP status code to use for validation errors.
Defaults to 422 . |
VERSIONING |
Enabled documents version control when
True . Can be overridden by resource
settings. Defaults to False . |
VERSIONS |
Suffix added to the name of the primary
collection to create the name of the shadow
collection to store document versions.
Defaults to _versions . When
VERSIONING is enabled , a collection
such as myresource_versions would be
created for a resource with a datasource of
myresource . |
VERSION_PARAM |
The URL query parameter used to access the
specific version of a document. Defaults to
version . Omit this parameter to get the
latest version of a document or use
?version=all` to get a list of all
version of the document. Only valid for
individual item endpoints. |
VERSION |
Field used to store the version number of a
document. Defaults to _version . |
LATEST_VERSION |
Field used to store the latest version number
of a document. Defaults to
_latest_version . |
VERSION_ID_SUFFIX |
Used in the shadow collection to store the
document id. Defaults to _document . If
ID_FIELD is set to _id , the
document id will be stored in field
_id_document . |
MONGO_HOST |
MongoDB server address. Defaults to localhost . |
MONGO_PORT |
MongoDB port. Defaults to 27017 . |
MONGO_USERNAME |
MongoDB user name. |
MONGO_PASSWORD |
MongoDB password. |
MONGO_DBNAME |
MongoDB database name. |
MONGO_QUERY_BLACKLIST |
A list of Mongo query operators that are not
allowed to be used in resource filters
( Mongo JavaScript operators are disabled by default, as they might be used as vectors for injection attacks. Javascript queries also tend to be slow and generally can be easily replaced with the (very rich) Mongo query dialect. |
MONGO_WRITE_CONCERN |
A dictionary defining MongoDB write concern
settings. All standard write concern
settings (w, wtimeout, j, fsync) are
supported. Defaults to Please be aware that setting ‘w’ to a value of 2 or greater requires replication to be active or you will be getting 500 errors (the write will still happen; Mongo will just be unable to check that it’s being written to multiple servers). Can be overridden at endpoint (Mongo
collection) level. See
|
DOMAIN |
A dict holding the API domain definition. See Domain Configuration. |
EXTENDED_MEDIA_INFO |
A list of properties to forward from the file upload driver. |
RETURN_MEDIA_AS_BASE64_STRING |
Controls the embedding of the media type in
the endpoint response. This is useful when
you have other means of getting the binary
(like custom Flask endpoints) but still
want clients to be able to POST/PATCH it.
Defaults to True . |
OPLOG |
Set it to True to enable the Operations Log.
Defaults to False . |
OPLOG_NAME |
This is the name of the database collection
where the Operations Log is stored. Defaults
to oplog . |
OPLOG_METHODS |
List of HTTP methods which operations
should be logged in the Operations Log.
Defaults to ['DELETE', 'POST, 'PATCH',
'PUT'] . |
OPLOG_ENDPOINT |
Name of the Operations Log endpoint. If the
endpoint is enabled it can be configured
like any other API endpoint. Set it to
None to disable the endpoint. Defaults
to None . |
OPLOG_AUDIT |
Set it to True to enable the audit
feature. When audit is enabled client IP
and document changes are also logged to the
Operations Log. Defaults to True . |
Domain Configuration¶
In Eve terminology, a domain is the definition of the API structure, the area where you design your API, fine-tune resources endpoints, and define validation rules.
DOMAIN
is a global configuration setting: a Python
dictionary where keys are API resources and values their definitions.
# Here we define two API endpoints, 'people' and 'works', leaving their
# definitions empty.
DOMAIN = {
'people': {},
'works': {},
}
In the following two sections, we will customize the people resource.
Resource / Item Endpoints¶
Endpoint customization is mostly done by overriding some global settings, but other unique settings are also available. Resource settings are always lowercase.
url |
The endpoint URL. If omitted the resource key
of the You can also use regexes to setup subresource-like endpoints. See Sub Resources. |
allowed_filters |
List of fields on which filtering is allowed.
Can be set to Please note: If API scraping or DB DoS
attacks are a concern, then globally disabling
filters (see |
sorting |
True if sorting is enabled, False
otherwise. Locally overrides SORTING . |
pagination |
True if pagination is enabled, False
otherwise. Locally overrides PAGINATION . |
resource_methods |
A list of HTTP methods supported at resource
endpoint. Allowed values: Please note: if you’re running version 0.0.5
or earlier use the now unsupported |
public_methods |
A list of HTTP methods supported at resource
endpoint, open to public access even when
Authentication and Authorization is enabled. Locally overrides
PUBLIC_METHODS . |
item_methods |
A list of HTTP methods supported at item
endpoint. Allowed values: GET , PATCH
and DELETE . PATCH or, for clients not
supporting PATCH, POST with the
X-HTTP-Method-Override header tag.
Locally overrides ITEM_METHODS . |
public_item_methods |
A list of HTTP methods supported at item
endpoint, left open to public access when
Authentication and Authorization is enabled. Locally overrides
PUBLIC_ITEM_METHODS . |
allowed_roles |
A list of allowed roles for resource
endpoint. See Authentication and Authorization for more
information. Locally overrides
ALLOWED_ROLES . |
allowed_read_roles |
A list of allowed roles for resource
endpoint with GET and OPTIONS methods.
See Authentication and Authorization for more
information. Locally overrides
ALLOWED_READ_ROLES . |
allowed_write_roles |
A list of allowed roles for resource
endpoint with POST, PUT and DELETE.
See Authentication and Authorization for more
information. Locally overrides
ALLOWED_WRITE_ROLES . |
allowed_item_read_roles |
A list of allowed roles for item endpoint
with GET and OPTIONS methods.
See Authentication and Authorization for more information.
Locally overrides ALLOWED_ITEM_READ_ROLES . |
allowed_item_write_roles |
A list of allowed roles for item endpoint
with PUT, PATH and DELETE methods.
See Authentication and Authorization for more information.
Locally overrides ALLOWED_ITEM_WRITE_ROLES . |
allowed_item_roles |
A list of allowed roles for item endpoint.
See Authentication and Authorization for more information.
Locally overrides ALLOWED_ITEM_ROLES . |
cache_control |
Value of the Cache-Control header field
used when serving GET requests. Leave empty
if you don’t want to include cache directives
with API responses. Locally overrides
CACHE_CONTROL . |
cache_expires |
Value (in seconds) of the Expires header
field used when serving GET requests. If
set to a non-zero value, the header will
always be included, regardless of the setting
of CACHE_CONTROL . Locally overrides
CACHE_EXPIRES . |
item_lookup |
True if item endpoint should be available,
False otherwise. Locally overrides
ITEM_LOOKUP . |
item_lookup_field |
Field used when looking up a resource
item. Locally overrides ITEM_LOOKUP_FIELD . |
item_url |
Rule used to construct item endpoint URL.
Locally overrides ITEM_URL . |
resource_title |
Title used when building resource links
(HATEOAS). Defaults to resource’s url . |
item_title |
Title to be used when building item references,
both in XML and JSON responses. Overrides
ITEM_TITLE . |
additional_lookup |
Besides the standard item endpoint which
defaults to /<resource>/<ID_FIELD_value> ,
you can optionally define a secondary,
read-only, endpoint like
/<resource>/<person_name> . You do so by
defining a dictionary comprised of two items
field and url. The former is the name of
the field used for the lookup. If the field
type (as defined in the resource schema) is
a string, then you put a URL rule in url. If
it is an integer, then you just omit url, as
it is automatically handled. See the code
snippet below for an usage example of this
feature. |
datasource |
Explicitly links API resources to database collections. See Advanced Datasource Patterns. |
auth_field |
Enables User-Restricted Resource Access. When the
feature is enabled, users can only
read/update/delete resource items created by
themselves. The keyword contains the actual
name of the field used to store the id of
the user who created the resource item. Locally
overrides AUTH_FIELD . |
allow_unknown |
When True , this option will allow insertion
of arbitrary, unknown fields to the endpoint.
Use with caution. Locally overrides
ALLOW_UNKNOWN . See Allowing the Unknown for more
information. Defaults to False . |
projection |
When True , this option enables the
Projections feature. Locally overrides
PROJECTION . Defaults to True . |
embedding |
When True this option enables the
Embedded Resource Serialization feature. Defaults to
True . |
extra_response_fields |
Allows to configure a list of additional
document fields that should be provided with
every POST response. Normally only
automatically handled fields (ID_FIELD ,
LAST_UPDATED , DATE_CREATED , ETAG )
are included in response payloads. Overrides
EXTRA_RESPONSE_FIELDS . |
hateoas |
When False , this option disables
HATEOAS for the resource.
Defaults to True . |
mongo_write_concern |
A dictionary defining MongoDB write concern
settings for the endpoint datasource. All
standard write concern settings (w, wtimeout, j,
fsync) are supported. Defaults to Please be aware that setting ‘w’ to a value of 2 or greater requires replication to be active or you will be getting 500 errors (the write will still happen; Mongo will just be unable to check that it’s being written to multiple servers.) |
authentication |
A class with the authorization logic for the
endpoint. If not provided the eventual
general purpose auth class (passed as
application constructor argument) will be used.
For details on authentication and authorization
see Authentication and Authorization. Defaults to None , |
embedded_fields |
A list of fields for which Embedded Resource Serialization
is enabled by default. For this feature to work
properly fields in the list must be
embeddable , and embedding must be
active for the resource. |
query_objectid_as_string |
When enabled the Mongo parser will avoid
automatically casting electable strings to
ObjectIds. This can be useful in those rare
occurrences where you have string fields in the
database whose values can actually be casted to
ObjectId values, but shouldn’t. Only effects
queries (?where= ). Defaults to False . |
internal_resource |
When True , this option makes the resource
internal. No HTTP action can be performed on
the endpoint, which is still accessible from
the Eve data layer. See
Internal Resources for more
informations. Defaults to False . |
schema |
A dict defining the actual data structure being handled by the resource. Enables data validation. See Schema Definition. |
Here’s an example of resource customization, mostly done by overriding global API settings:
people = {
# 'title' tag used in item links. Defaults to the resource title minus
# the final, plural 's' (works fine in most cases but not for 'people')
'item_title': 'person',
# by default, the standard item entry point is defined as
# '/people/<ObjectId>/'. We leave it untouched, and we also enable an
# additional read-only entry point. This way consumers can also perform
# GET requests at '/people/<lastname>'.
'additional_lookup': {
'url': 'regex("[\w]+")',
'field': 'lastname'
},
# We choose to override global cache-control directives for this resource.
'cache_control': 'max-age=10,must-revalidate',
'cache_expires': 10,
# we only allow GET and POST at this resource endpoint.
'resource_methods': ['GET', 'POST'],
}
Schema Definition¶
Unless your API is read-only, you probably want to define resource schemas. Schemas are important because they enable proper validation for incoming streams.
# 'people' schema definition
'schema'= {
'firstname': {
'type': 'string',
'minlength': 1,
'maxlength': 10,
},
'lastname': {
'type': 'string',
'minlength': 1,
'maxlength': 15,
'required': True,
'unique': True,
},
# 'role' is a list, and can only contain values from 'allowed'.
'role': {
'type': 'list',
'allowed': ["author", "contributor", "copy"],
},
# An embedded 'strongly-typed' dictionary.
'location': {
'type': 'dict',
'schema': {
'address': {'type': 'string'},
'city': {'type': 'string'}
},
},
'born': {
'type': 'datetime',
},
}
As you can see, schema keys are the actual field names, while values are dicts defining the field validation rules. Allowed validation rules are:
type |
Field data type. Can be one of the following:
If the MongoDB data layer is used, then geographic data structures are also allowed:
See GeoJSON for more informations. |
required |
If True , the field is mandatory on
insertion. |
readonly |
If True , the field is readonly. |
minlength , maxlength |
Minimum and maximum length allowed for
string and list types. |
min , max |
Minimum and maximum values allowed for
integer , float and number types. |
allowed |
List of allowed values for string and
list types. |
empty |
Only applies to string fields. If False ,
validation will fail if the value is empty.
Defaults to True . |
items |
Defines a list of values allowed in a list
of fixed length. |
schema |
Validation schema for dict types and
arbitrary length list types. For details
and usage examples, see Cerberus documentation |
unique |
The value of the field must be unique within the collection. Please note: validation constraints are checked against the database, and not between the payload documents themselves. This causes an interesting corner case: in the event of a multiple documents payload where two or more documents carry the same value for a field where the ‘unique’ constraint is set, the payload will validate successfully, as there are no duplicates in the database (yet). If this is an issue, the client can always send the documents one at a time for insertion, or validate locally before submitting the payload to the API. Also be aware that when User-Restricted Resource Access is enabled the rule will be validated against user data only. So in this scenario duplicates are allowed as long as they are stored by different users. Conversely, a single user cannot store duplicate values. |
data_relation |
Allows to specify a referential integrity rule that the value must satisfy in order to validate. It is a dict with three keys:
|
nullable |
If True , the field value can be set to
None . |
default |
The default value for the field. When serving POST and PUT requests, missing fields will be assigned the configured default values. It works also for types schema = {
# Simple default
'title': {
'type': 'string',
'default': 'M.'
},
# Default in a dict
'others': {
'type': 'dict',
'schema': {
'code': {
'type': 'integer',
'default': 100
}
}
},
# Default in a list of dicts
'mylist': {
'type': 'list',
'schema': {
'type': 'dict',
'schema': {
'name': {'type': 'string'},
'customer': {
'type': 'boolean',
'default': False
}
}
}
}
}
|
versioned |
If True , this field will be included in the
versioned history of each document when
versioning is enabled. Defaults to True . |
keyschema |
Validation schema for all values of a dict .
The dict can have arbitrary keys, the values
for all of which must validate with given
schema. See keyschema example. |
regex |
Validation will fail if field value does not match the provided regex rule. Only applies to string fields. See email validation example |
dependencies |
This rule allows a list of fields that must be present in order for the target field to be allowed. See dependencies example |
Schema syntax is based on Cerberus and yes, it can be extended. In fact, Eve
itself extends the original grammar by adding the unique
and
data_relation
keywords, along with the objectid
datatype. For more
information on custom validation and usage examples see Data Validation.
In Resource / Item Endpoints you customized the people endpoint. Then, in this section, you defined people validation rules. Now you are ready to update the domain which was originally set up in Domain Configuration:
# add the schema to the 'people' resource definition
people['schema'] = schema
# update the domain
DOMAIN['people'] = people
Advanced Datasource Patterns¶
The datasource
keyword allows to explicitly link API resources to database
collections. If omitted, the domain resource key is assumed to also be the name
of the database collection. It is a dictionary with four allowed keys:
source |
Name of the database collection consumed by the resource. If omitted, the resource name is assumed to also be a valid collection name. See Multiple API Endpoints, One Datasource. |
filter |
Database query used to retrieve and validate data. If omitted, by default the whole collection is retrievied. See Predefined Database Filters. |
projection |
Fieldset exposed by the endpoint. If omitted, by default all fields will be returned to the client. See Limiting the Fieldset Exposed by the API Endpoint. |
default_sort |
Default sorting for documents retrieved at the endpoint. If omitted, documents will be returned with the default database order. A valid statement would be:
For more informations on sort and filters see Filtering. |
Predefined Database Filters¶
Database filters for the API endpoint are set with the filter
keyword.
people = {
'datasource': {
'filter': {'username': {'$exists': True}}
}
}
In the example above, the API endpoint for the people resource will only expose and update documents with an existing username field.
Predefined filters run on top of user queries (GET requests with where clauses) and standard conditional requests (If-Modified-Since, etc.)
Please note that datasource filters are applied on GET, PATCH and DELETE requests. If your resource allows POST requests (document insertions), then you will probably want to set the validation rules accordingly (in our example, ‘username’ should probably be a required field).
Static vs Dynamic filters
Predefined filters are static. You can also exploit the Event Hooks
system (specifically, on_pre_<METHOD>
hooks) to set up dynamic filters
instead.
Multiple API Endpoints, One Datasource¶
Multiple API endpoints can target the same database collection. For
example you can set both /admins
and /users
to read and write from
the same people collection on the database.
people = {
'datasource': {
'source': 'people',
'filter': {'userlevel': 1}
}
}
The above setting will retrieve, edit and delete only documents from the people collection with a userlevel of 1.
Limiting the Fieldset Exposed by the API Endpoint¶
By default API responses to GET requests will include all fields defined by the
corresponding resource schema. The projection
setting of the datasource
resource keyword allows you to redefine the fieldset.
people = {
'datasource': {
'projection': {'username': 1}
}
}
The above setting will expose only the username field to GET requests, no matter the schema defined for the resource.
Likewise, you can exclude fields from API responses:
people = {
'datasource': {
'projection': {'username': 0}
}
}
The above will include all document fields but username.
Please note that POST and PATCH methods will still allow the whole schema to be manipulated. This feature can come in handy when, for example, you want to protect insertion and modification behind an Authentication and Authorization scheme while leaving read access open to the public.