Tutorial
This quick tutorial will get you up and running with your first gREST project. Your project should include at most three files to have a working API for your first model. You project layout should be like this:
Note: By installing pygrest
package, all the necessary dependencies would also be installed.
app/
main.py # Main gREST application
models.py # Database model of your first node (User)
users_view.py # User's endpoints is defined here
Your main.py
file should setup a Flask application, configure database connection, enable logging and register a view:
import os
import logging
import neomodel
from flask import Flask
from grest import global_config
from users_view import UsersView
def create_app():
# create flask app
app = Flask(__name__)
# add a simple endpoint for testing purposes
@app.route('/')
def index():
return "Hello World!"
# configure connection to database
neomodel.config.DATABASE_URL = global_config.DB_URL # The bolt URL of your Neo4j instance
neomodel.config.AUTO_INSTALL_LABELS = True
neomodel.config.FORCE_TIMEZONE = True # default False
# attach logger to flask's app logger
app.ext_logger = app.logger
# register users' view
UsersView.register(app, route_base="/users", trailing_slash=False)
return app
if __name__ == '__main__':
app = create_app()
app.run(host="localhost", port=5000)
Next you should define your models with Neomodel syntax. Neomodel is easier to use than other ORMs and drivers. Your models.py
file would be like this:
from neomodel import (StructuredNode, UniqueIdProperty, StringProperty, BooleanProperty)
from grest import models
class User(StructuredNode, models.Node):
user_id = UniqueIdProperty()
first_name = StringProperty()
last_name = StringProperty()
email = StringProperty()
is_enabled = BooleanProperty(default=False)
As you can see, we have imported Node
from grest.models
, so that we can use the Node
mixin (which is used in JSON serialization of model data and automatic input validation). Also note that the Person
class (model) is inheriting from two parents: StructuredNode
and Node
.
Now that you've defined your model, you should also define a simple view to contain your model (remember, we have registered this view in main.py
). This is where the beauty of the gREST framework comes in:
from grest import GRest
from models import User
class UsersView(GRest):
__model__ = {"primary": User}
__selection_field__ = {"primary": "user_id"}
The most important part of gREST is __model__
and __selection_field__
properties. They contain the logic to access your models and relations. As you see, our primary
model is User
and its primary key (so to say) is user_id
, so the selection field of the primary model is user_id
.
To run this app, simply execute it via the python command:
python main.py
A webserver would start on port 5000 in debug mode, so that you can test your endpoints. To test your new API, use a simple HTTP client (e.g. curl) to query the API:
curl -H "Content-Type: application/json" -X POST -d '{"first_name":"John","last_name":"Doe","email":"johndoe@example.com"}' http://localhost:5000/users
Result would be like this:
{"user_id":"937a8d5c1a3a4617bea9ff9b2428778a"}