Configuration¶
Generally Eve configuration is best done with configuration files. The
configuration files themselves are actual Python files. However, Eve will
give precedence to dictionary-based settings first, then it will try to
locate a file passed in EVE_SETTINGS
environmental variable (if
set) and finally it will try to locate settings.py or a file with filename
passed to settings flag in constructor.
Configuration With Files¶
On startup, if settings flag is omitted in constructor, Eve will try to locate file named settings.py, first in the application folder and then in one of the application’s subfolders. You can choose an alternative filename/path, just pass it as an argument when you instantiate the application. If the file path is relative, Eve will try to locate it recursively in one of the folders in your sys.path, therefore you have to be sure that your application root is appended to it. This is useful, for example, in testing environments, when settings file is not necessarily located in the root of your 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. Unlike configuring Eve with the settings file, dictionary-based approach will only update Eve’s default settings with your own values, rather than overwriting all the settings.
from eve import Eve
my_settings = {
'MONGO_HOST': 'localhost',
'MONGO_PORT': 27017,
'MONGO_DBNAME': 'the_db_name',
'DOMAIN': {'contacts': {}}
}
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:
# 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 for all API endpoints. Will be
used in conjunction with |
|
API version. Will be used in conjunction with
|
|
List of fields on which filtering is allowed.
Entries in this list work in a hierarchical
way. This means that, for instance, filtering
on 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. |
|
Whether to validate the filters against the
resource schema. Invalid filters will throw
an exception. Defaults to Word of caution: validation on filter
expressions involving fields with custom
rules or types might have a considerable
impact on performance. This is the case,
for example, with |
|
|
|
|
|
Maximum value allowed for |
|
Default value for |
|
Set this to |
|
Key for the filters query parameter. Defaults to |
|
Key for the sort query parameter. Defaults to |
|
Key for the projections query parameter. Defaults to |
|
Key for the pages query parameter. Defaults to |
|
Key for the max results query parameter. Defaults to |
|
Key for the embedding query parameter. Defaults to |
|
Key for the aggregation query parameter.
Defaults to |
|
A Python date format used to parse and render
datetime values. When serving requests,
matching JSON strings will be parsed and
stored as |
|
A list of HTTP methods supported at resource
endpoints. Allowed values: |
|
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 |
|
A list of HTTP methods supported at item
endpoints. Allowed values: |
|
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 |
|
A list of allowed roles for resource
endpoints. Can be overridden by resource
settings. See Authentication and Authorization for more
information. Defaults to |
|
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 |
|
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 |
|
A list of allowed roles for item endpoints.
See Authentication and Authorization for more information. Can
be overridden by resource settings.
Defaults to |
|
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 |
|
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 |
|
Enables / Disables global the possibility
to override the sent method with a header
|
|
Value of the |
|
Value (in seconds) of the |
|
CORS (Cross-Origin Resource Sharing) support.
Allows API maintainers to specify which
domains are allowed to perform CORS
requests. Allowed values are: |
|
The same setting as |
|
CORS (Cross-Origin Resource Sharing) support.
Allows API maintainers to specify which
headers are allowed to be sent with CORS
requests. Allowed values are: |
|
CORS (Cross-Origin Resource Sharing) support.
Allows API maintainers to specify which
headers are exposed within a CORS response.
Allowed values are: |
|
CORS (Cross-Origin Resource Sharing) support.
Allows API maintainers to specify if cookies can
be sent by clients.
The only allowed value is: |
|
CORS (Cross-Origin Resource Sharing) support. Allows to set max age for the access control allow header. Defaults to 21600. |
|
Name of the field used to record a document’s
last update date. This field is
automatically handled by Eve. Defaults to
|
|
Name for the field used to record a document
creation date. This field is automatically
handled by Eve. Defaults to |
|
Name of the field used to uniquely identify
resource items within the database. You
want this field to be properly indexed on
the database. Can be overridden by resource
settings. Defaults to |
|
|
|
Document field used when looking up a resource
item. Can be overridden by resource
settings. Defaults to |
|
URL rule used to construct default item
endpoint URLs. Can be overridden by
resource settings. Defaults
|
|
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. |
|
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 |
|
When |
|
When |
|
When |
|
When |
|
Allows to configure a list of additional
document fields that should be provided
with every POST response. Normally only
automatically handled fields ( |
|
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, |
|
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 |
|
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 |
|
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 |
|
|
|
Allows to customize the error_code field. Defaults
to |
|
When |
|
Allows to customize the issues field. Defaults
to |
|
Allows to customize the status field. Defaults
to |
|
Status message returned when data validation is
successful. Defaults to |
|
Status message returned when data validation
failed. Defaults to |
|
Allows to customize the items field. Defaults
to |
|
Allows to customize the meta field. Defaults
to |
|
String value to include an info section, with the
given INFO name, at the Eve homepage (suggested
value |
|
Allows to customize the links field. Defaults
to |
|
Allows to customize the etag field. Defaults
to |
|
|
|
|
|
Allows to change enabled renderers. Defaults to
|
|
|
|
Supported JSON content types. Useful when
you need support for vendor-specific json
types. Please note: responses will still
carry the standard |
|
The HTTP status code to use for validation errors.
Defaults to |
|
Enabled documents version control when
|
|
Suffix added to the name of the primary
collection to create the name of the shadow
collection to store document versions.
Defaults to |
|
The URL query parameter used to access the
specific version of a document. Defaults to
|
|
Field used to store the version number of a
document. Defaults to |
|
Field used to store the latest version number
of a document. Defaults to
|
|
Used in the shadow collection to store the
document id. Defaults to |
|
A MongoDB URI which is used in preference of the other configuration variables. |
|
MongoDB server address. Defaults to |
|
MongoDB port. Defaults to |
|
MongoDB user name. |
|
MongoDB password. |
|
MongoDB database name. |
|
MongoDB keyword arguments to passed to
MongoClient class |
|
MongoDB authorization database. Defaults to |
|
MongoDB authentication mechanism.
See PyMongo Authentication Mechanisms.
Defaults to |
|
Specify MongoDB extra authentication mechanism properties
if required. Defaults to |
|
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. |
|
A list of extra Mongo query operators to allow
besides the official list of allowed operators.
Defaults to Can be overridden at endpoint (Mongo
collection) level. See
|
|
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
|
|
A dict holding the API domain definition. See Domain Configuration. |
|
A list of properties to forward from the file upload driver. |
|
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 |
|
Set it to |
|
Base URL to be used when
|
|
The media endpoint to be used when
|
|
Format of a file url served at the
dedicated media endpoints. Defaults to
|
|
In case you are submitting your resource as
|
|
If set to When using this together with
Defaults to |
|
When submitting a non Defaults to |
|
Set it to |
|
This is the name of the database collection
where the Operations Log is stored. Defaults
to |
|
List of HTTP methods which operations
should be logged in the Operations Log.
Defaults to |
|
List of HTTP methods which operations
will include changes into the Operations Log entry.
Defaults to |
|
Name of the Operations Log endpoint. If the
endpoint is enabled it can be configured
like any other API endpoint. Set it to
|
|
Set it to |
|
When enabled, the optional |
|
Name of the The Schema Endpoint. Defaults
to |
|
Custom header containing total count of
items in response payloads for collection
|
|
This option will cause the response to be
wrapped in a JavaScript function call if
the argument is set in the request. For
example if you set |
|
Enables bulk insert when set to |
|
Enables soft delete when set to |
|
Field name used to indicate if a document
has been deleted when |
|
The URL query parameter used to include soft deleted items in resource level GET responses. Defaults to ‘show_deleted’. |
|
This is a list of HTTP error codes for
which a standard API response will be
provided. Canonical error response includes
a JSON body with actual error code and
description. Set this to an empty list if
you want to disable canonical responses
altogether. Defaults to |
|
If |
|
|
|
If |
|
If |
|
If |
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.
|
The endpoint URL. If omitted the resource key
of the You can also use regexes to setup subresource-like endpoints. See Sub Resources. |
|
List of fields on which filtering is allowed.
Entries in this list work in a hierarchical
way. This means that, for instance, filtering
on Please note: If API scraping or DB DoS
attacks are a concern, then globally disabling
filters (see |
|
|
|
|
|
Maximum value allowed for |
|
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 |
|
A list of HTTP methods supported at resource
endpoint, open to public access even when
Authentication and Authorization is enabled. Locally overrides
|
|
A list of HTTP methods supported at item
endpoint. Allowed values: |
|
A list of HTTP methods supported at item
endpoint, left open to public access when
Authentication and Authorization is enabled. Locally overrides
|
|
A list of allowed roles for resource
endpoint. See Authentication and Authorization for more
information. Locally overrides
|
|
A list of allowed roles for resource
endpoint with GET and OPTIONS methods.
See Authentication and Authorization for more
information. Locally overrides
|
|
A list of allowed roles for resource
endpoint with POST, PUT and DELETE.
See Authentication and Authorization for more
information. Locally overrides
|
|
A list of allowed roles for item endpoint
with GET and OPTIONS methods.
See Authentication and Authorization for more information.
Locally overrides |
|
A list of allowed roles for item endpoint
with PUT, PATH and DELETE methods.
See Authentication and Authorization for more information.
Locally overrides |
|
A list of allowed roles for item endpoint.
See Authentication and Authorization for more information.
Locally overrides |
|
Value of the |
|
Value (in seconds) of the |
|
Field used to uniquely identify resource items
within the database. Locally overrides
|
|
|
|
Field used when looking up a resource
item. Locally overrides |
|
Rule used to construct item endpoint URL.
Locally overrides |
|
Title used when building resource links
(HATEOAS). Defaults to resource’s |
|
Title to be used when building item references,
both in XML and JSON responses. Overrides
|
|
Besides the standard item endpoint which
defaults to |
|
Explicitly links API resources to database collections. See Advanced Datasource Patterns. |
|
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 |
|
When |
|
When |
|
When |
|
Allows to configure a list of additional
document fields that should be provided with
every POST response. Normally only
automatically handled fields ( |
|
When |
|
A list of extra Mongo query operators to allow
for this endpoint besides the official list of
allowed operators. Defaults to |
|
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.) |
|
Allows overriding of the default For example if This allows for eventually serving data from a different database/server at every endpoint. See also: Auth-driven Database Access. |
|
Allows to specify a set of indexes to be created for this resource before the app is launched. Indexes are expressed as a dict where keys are
index names and values are either a list of
tuples of (field, direction) pairs, or
a tuple with a list of field/direction pairs
and index options expressed as a dict, such
as Multiple pairs are used to create compound
indexes. Direction takes all kind of values
supported by PyMongo, such as Please note: keep in mind that index design, creation and maintenance is a very important task and should be planned and executed with great care. Usually it is also a very resource intensive operation. You might therefore want to handle this task manually, out of the context of API instantiation. Also remember that, by default, any already existent index for which the definition has been changed, will be dropped and re-created. |
|
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 |
|
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
|
|
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. It effects
queries ( |
|
When |
|
List of fields that
should not be used to compute the ETag value.
Defaults to |
|
A dict defining the actual data structure being handled by the resource. Enables data validation. See Schema Definition. |
|
When |
|
When |
|
If |
|
If |
|
If |
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:
|
Field data type. Can be one of the following:
If the MongoDB data layer is used then
See GeoJSON for more information geo fields. |
|
If |
|
If |
|
Minimum and maximum length allowed for
|
|
Minimum and maximum values allowed for
|
|
List of allowed values for |
|
Only applies to string fields. If |
|
Defines a list of values allowed in a |
|
Validation schema for |
|
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. |
|
The field value is unique to the user. This is useful when User-Restricted Resource Access is enabled on an endpoint. 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. If URRA is not active on the endpoint, this
rule behaves like |
|
The value of the field must be unique within the resource. This differs from the |
|
Allows to specify a referential integrity rule that the value must satisfy in order to validate. It is a dict with four keys:
|
|
If |
|
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
}
}
}
}
}
|
|
Enabled documents version control when |
|
If |
|
Validation schema for all values of a |
|
This is the counterpart to |
|
Validation will fail if field value does not match the provided regex rule. Only applies to string fields. See regex in Cerberus docs. |
|
This rule allows a list of fields that must be present in order for the target field to be allowed. See dependencies in Cerberus docs. |
|
This rule allows you to list multiple sets of rules to validate against. The field will be considered valid if it validates against one set in the list. See *of-rules in Cerberus docs. |
|
Same as |
|
Same as |
|
Same as |
|
Type coercion allows you to apply a callable to a value before any other validators run. The return value of the callable replaces the new value in the document. This can be used to convert values or sanitize data before it is validated. See value coercion in Cerberus docs. |
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:
|
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. |
|
Database query used to retrieve and validate data. If omitted, by default the whole collection is retrieved. See Predefined Database Filters. |
|
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 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 information on sort and filters see Filtering. |
|
Aggregation pipeline and options. When used all
other This is a dictionary with one or more of the following keys:
You only need to set |
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.
When you want to hide some secret fields from client, you should use inclusive projection setting and include all fields should be exposed. While, when you want to limit default responses to certain fields but still allow them to be accessible through client-side projections, you should use exclusive projection setting and exclude fields should be omitted.
The following is an example for inclusive projection setting:
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. And other fields will not be exposed even by client-side projection. The following API call will not return lastname or born.
$ curl -i http://myapi/people?projection={"lastname": 1, "born": 1}
HTTP/1.1 200 OK
You can also exclude fields from API responses. But this time, the excluded fields will be exposed to client-side projection. The following is an example for exclusive projection setting:
people = {
'datasource': {
'projection': {'username': 0}
}
}
The above will include all document fields but username. However, the following API call will return username this time. Thus, you can exploit this behaviour to serve media fields or other expensive fields.
In most cases, none or inclusive projection setting is preferred. With inclusive projection, secret fields are taken care from server side, and default fields returned can be defined by short-cut functions from client-side.
$ curl -i http://myapi/people?projection={"username": 1}
HTTP/1.1 200 OK
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.