Quickstart Guide for Python Eve: Setting up

Python REST API framework designed for human beings

Python REST API framework designed for human beings

Problems I faced

I have known about Python eve framework for quite some time now. But recently I thought of using it in my project because of its usefulness. And then I hit a roadblock of less documentation and took me a good amount of time to master it. So, this article is an empathetic effort, empathy for those who may have to travel the same boat for some time and do not have to suffer the same pain as I did.

Setting-up

To install the eve package, the command(assuming you have pip already installed) is

pip install eve

A Minimal Application

We will start with a top-to-bottom approach to show you the simplicity of Eve. In a file “run.py”, you have 3 lines of code that you need to run.

from eve import Eveapp = Eve()if __name__ == '__main__':
    app.run()

Next we have to create a new text file at the same place where run.py exists and name it as settings.py. It contains the following:

DOMAIN = {'users': {}}

This is the Eve configuration file, a standard Python module, and it is telling Eve that your API is comprised of just one accessible resource, user.

Now we are ready to launch our API.

$ python run.py
 * Running on http://127.0.0.1:5000/

Now, let us understand what has happened. So, we have created a Read-only API from Eve as this is by default and without any schema definition.

Database Inclusion

We add the database connection by adding the following lines to settings.py:

# Let's just use the local mongod instance. Edit as needed.# 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# Skip this block if your db has no auth. But it really should.
MONGO_USERNAME = '<your username>'
MONGO_PASSWORD = '<your password>'
# Name of the database on which the user can be authenticated,
# needed if --auth mode is enabled.
MONGO_AUTH_SOURCE = '<dbname>'. MONGO_DBNAME = 'users_ms'

These things are enough to start using in Mongo due to mongo’s laziness as in POST request a new database and new collection will be created with entry if nothing exists but the performance issue will be persistent as it will be without optimization and indexes due to auto-managed databases.

Real-life Application

We create a new directory named schema and a text file as user_schema.py inside it and store the collection schema here. For multiple collections we can define different schema files and later import it to settings file of eve.

users_schema = {
    'user_name': {
        'type': 'string',
        'minlength': 1,
        'maxlength': 50,
        'required': True,
        # talk about hard constraints! For the purpose of the demo
        # 'lastname' is an API entry-point, so we need it to be        unique.
        'unique': True,
    },
    'user_education': {
        'type': 'integer',
        'minlength': 1,
        'maxlength': 4,
        'required': True,
        # talk about hard constraints! For the purpose of the demo
    },
    # An embedded 'strongly-typed' dictionary.
    'question_json': {
        'schema': {
            'question': {'type': 'string'},
            'answer': {'type': 'string'}
        },'required': True,
    },# 'role' is a list, and can only contain values from 'allowed'.
    'role': {
        'type': 'list',
        'allowed': ["author", "contributor", "copy"],
    }
}

Now, we come back to settings.py file and make further customization there for the above changes.

users = {
    'item_title': 'users',
# Enable GET, POST, DELETE for resources/collections.              
# (if we omit this line, the API will default to ['GET'] and provide
# read-only access to the endpoint).
    'resource_methods': ['GET', 'POST'],
# Enable GET, PATCH, PUT and deletes #of individual items'item_methods': ['GET', 'PATCH', 'DELETE'],    'schema': users_schema
}
DOMAIN = {
    'users': users,
}

Finally, our settings.py file will look like this:

from schema import users_schema
# Let's just use the local mongod instance. Edit as needed.# 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# Skip this block if your db has no auth. But it really should.
MONGO_USERNAME = '<your username>'
MONGO_PASSWORD = '<your password>'
# Name of the database on which the user can be authenticated,
# needed if --auth mode is enabled.
MONGO_AUTH_SOURCE = '<dbname>'. MONGO_DBNAME = 'users_ms'users = {
    'item_title': 'users',
# Enable GET, POST, DELETE for resources/collections.              
# (if we omit this line, the API will default to ['GET'] and provide
# read-only access to the endpoint).
    'resource_methods': ['GET', 'POST'],
# Enable GET, PATCH, PUT and deletes #of individual items'item_methods': ['GET', 'PATCH', 'DELETE'],    'schema': users_schema
}
DOMAIN = {
    'users': users,
}

Save settings.py and launch run.py. We can now insert documents at the users endpoint:

$ curl -d '[{"user_name":"Sagar Malik","user_education":12,"question_json":{"Question":"What is photosynthesis","answer":"It is the process by which plants make food"},"role":"author"},{"user_name":"Vartul Mittal","user_education":12,"question_json":{"Question":"What is photosynthesis","answer":"It is the process by which plants make food"},"role":"author"}]' -H 'Content-Type: application/json'  http://127.0.0.1:5000/users
HTTP/1.0 201 OK

We will get a similar response in the form of a list as we had sent POST request also in form of a list:

{
    "_status": "OK",
    "_items": [
        {
            "_updated": "Fri, 05 Jun 2020 02:30:56 GMT",
            "_created": "Fri, 05 Jun 2020 02:30:56 GMT",
            "_etag": "fbd77aca5e59b9a0751c6f549f890692aa0d10c3",
            "_id": "5ed9ae60dbdf8c083f0ca30f",
            "_links": {
                "self": {
                    "title": "users",
                    "href": "users/5ed9ae60dbdf8c083f0ca30f"
                }
            },
            "_status": "OK"
        },
        {
            "_updated": "Fri, 05 Jun 2020 02:30:56 GMT",
            "_created": "Fri, 05 Jun 2020 02:30:56 GMT",
            "_etag": "364e0a5574f29e7fab9a84b293c0ffc1d02c2587",
            "_id": "5ed9ae60dbdf8c083f0ca310",
            "_links": {
                "self": {
                    "title": "users",
                    "href": "users/5ed9ae60dbdf8c083f0ca310"
                }
            },
            "_status": "OK"
        }
    ]
}

Now, we can have read (GET) from the href that is created inside _links. Also, pagination of results are automated in eve and we can directly access it by /collection_name?max_results=(_)&page=(_) and 25 results per page is generated by default if left empty.

Thus now we set up a simple RESTFUL API(but fairly complex if Eve would not have been there). Eve comes in with default support for MongoDB but we can use other SQL and NoSQL databases. To read more about the superpowers and what can be achieved by Eve here.

Thanks for reading the article and I hope it would have solved your doubts and aversions about Python Eve.