In the example above the same result would be achieved by simply exposing an invoices endpoint that clients could query this way: This otherwise legit GET request: By contrast, if you had a simple resource endpoint the document lookup would happen on a single field: This differs from the standard behavior, whereas a delete operation on a collection enpoint will cause the deletion of all the documents in the collection.
When you do grant access to item endpoints, you can define up to two lookups, both defined with regexes. The first will be the primary endpoint and will match your database primary key structure i. Wed, 21 Nov The second, which is optional and read-only, will match a field with unique values since Eve will retrieve only the first match anyway.
Since we are accessing the same item, in both cases the response payload will look something like this: Eve abides by providing one default endpoint per item. Adding a secondary endpoint is a decision that should be pondered carefully. Consider our example above. Actually the whole example is fubar, as there could be multiple people sharing the same last name, but you get the idea. Query strings are supported, allowing for filtering and sorting.
Both native Mongo queries and Python conditional expressions are supported. Here we are asking for all documents where lastname value is Doe: Native Python syntax works like this: Filters are enabled by default on all document fields. If scraping, or fear of DB DoS attacks by querying on non-indexed fields is a concern, then whitelisting allowed filters is the way to go. As you can see you simply prepend a minus to the field name if you need the sort order to be reversed for a field.
Please note Always use double quotes to wrap field names and values. Using single quotes will result in Bad Request responses. Default and maximum page size is customizable, and consumers can request specific pages via the query string: Please note that, for clarity, the above example is not properly escaped. If using curl, refer to the examples provided in Filtering. Links provide details on their relation relative to the resource being accessed, and a title.
Relations and titles can then be used by clients to dynamically updated their UI, or to navigate the API without knowing its structure beforehand. From there, any client could navigate the API just by following the links provided with every response. Please note that next, previous and last items will only be included when appropriate.
Well, if you know that your client application is not going to use the feature, then you might want to save on both bandwidth and performance. Inbound documents for inserts and edits are in JSON format. XMLRenderer' ] You can create your own renderer by subclassing eve. Each renderer should set valid mime attr and have. Please note that at least one renderer must always be enabled. These headers allow clients to perform conditional requests by using the If-Modified-Since header: Wed, 05 Dec An ETag is a hash value representing the current state of the resource on the server.
This prevents overwriting items with obsolete versions. Consider the following workflow: And the response payload looks something like this: Concurrency control applies to all edition methods: When concurrency control is disabled no ETag is provided with responses.
You should be careful about disabling this feature, as you would effectively open your API to the risk of older versions replacing your documents.
When concurrenncy check enforcement is disabled, requests with the If-Match header will be processed as conditional requests, and requests made without the If-Match header will not be processed as conditional. Its value is the URI to the new document. In order to reduce the number of loopbacks, a client might also submit multiple documents with a single request. All it needs to do is enclose the documents in a JSON list: In case of successful multiple inserts, keep in mind that the Location header only returns the URI of the first created document.
Your configuration includes a schema definition for every resource managed by the API. When all documents pass validation and are inserted correctly the response status is Created. For more information see Data Validation. Say that your API can only accept odd numbers for a certain field value; you can extend the validation class to validate that. Tue, 22 Jan These will minimize load on the server since cache-enabled consumers will perform resource-intensive request only when really needed.
When versioning is a necessity, different API versions should be isolated instances since so many things could be different between versions: By default, this setting is turned off, but it can be turned globally or configured individually for each resource. Behind the scenes, Eve stores document versions in shadow collections that parallels the collection of each primary resource that Eve defines.
A special new query parameter is available when GETing an item that provides access to the document versions. Access a specific version with? Collection query features like projections, pagination, and sorting work with all and diff except for sorting which does not work on diff. It is important to note that there are a few non-standard scenarios which could produce unexpected results when versioning is turned on. In particular, document history will not be saved when modifying collections outside of the Eve generated API.
At this time there will be multiple versions of the document with the same version number. Additionally, there are caching corner cases unique to document versions. This results in two corner cases. Second, a version fetched and cached in the same second that multiple new versions are created can receive incorrect Not Modified responses on ensuing GET queries due to Last-Modified values having a resolution of one second and the static etag values not providing indication of the changes.
For more information see and Global Configuration and Domain Configuration. OAuth2 can be easily integrated. You can lockdown the whole API, or just some endpoints. You can also restrict CRUD commands, like allowing open read-only access while restricting edits, inserts and deletes to authorized users.
Role-based access control is supported as well. For more information see Authentication and Authorization. Cross-origin resource sharing CORS is a more recent method of getting data from a server in a different domain, which addresses some of those criticisms. All modern browsers now support CORS making it a viable cross-browser alternative source.
When serving POST create requests, missing fields will be assigned the configured default values. See default and nullable keywords in Schema Definition for more informations.
This allows for multiple resource endpoints to seamlessly target the same database collection. Put another way, Projections are conditional queries where the client dictates which fields should be returned by the API. You can also exclude fields: Also keep in mind that some database engines, Mongo included, do not allow for mixing of inclusive and exclusive selections.
Clients have the power to activate document embedding on per-request basis by means of a query parameter. Suppose you have a emails resource configured like this: Furthermore, only fields with the embeddable value explicitly set to True will allow the embedding of referenced documents. If the listed fields are embeddable and they are actually referencing documents in other resources and embedding is enabled for the resource , then the referenced documents will be embedded by default.
Clients can still opt out from field that are embedded by default: This feature is about serialization on GET requests. Document embedding is enabled by default. Please note When it comes to MongoDB, what embedded resource serialization deals with is document references linked documents , something different from embedded documents, also supported by Eve see MongoDB Data Model Design. Embedded resource serialization is a nice feature that can really help with normalizing your data model for the client.
However, when deciding whether to enable it or not, especially by default, keep in mind that each embedded resource being looked up will require a database lookup, which can easily lead to performance issues. See Global Configuration and Domain Configuration for more information on enabling and configuring soft delete. This is to ensure that soft deleted documents included in responses reflect the state of a document when it was deleted, and do not to change if embedded documents are updated. By default, resource level GET requests will not include soft deleted items in their response.
Soft delete is enforced in the data layer, meaning queries made by application code using the app. Passing a request object with req.
For example, using PATCH requests, only the fields to be changed in the restored version would be specified, or an empty request would be made to restore the document as is. The request must be made with proper authorization for write permission to the soft deleted document or it will be refused. Be aware that, should a previously soft deleted document be restored, there is a chance that an eventual unique field might end up being now duplicated in two different documents: This is because soft deleted documents are ignored when validating the unique rule for new or updated documents.