This repository has been archived by the owner on Dec 13, 2022. It is now read-only.
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
1. wrote index, installation and tutorial
2. changed some mkdocs configurations
- Loading branch information
Showing
4 changed files
with
134 additions
and
17 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,17 +1,5 @@ | ||
# Welcome to MkDocs | ||
# gREST - Graph-based REST API Framework | ||
|
||
For full documentation visit [mkdocs.org](http://mkdocs.org). | ||
gREST is a RESTful API development framework on top of Python, Flask, Neo4j and Neomodel. Its primary purpose is to ease development of RESTful APIs with little effort and minimum amount of code. To achieve this, I've made choices to make it easy for developers to construct an API quickly and easily. | ||
|
||
## Commands | ||
|
||
* `mkdocs new [dir-name]` - Create a new project. | ||
* `mkdocs serve` - Start the live-reloading docs server. | ||
* `mkdocs build` - Build the documentation site. | ||
* `mkdocs help` - Print this help message. | ||
|
||
## Project layout | ||
|
||
mkdocs.yml # The configuration file. | ||
docs/ | ||
index.md # The documentation homepage. | ||
... # Other markdown pages, images and other files. | ||
Throughout this documentation, I will show you how to develop a simple API and customize it wherever and whenever you want! |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,31 @@ | ||
# Installation | ||
|
||
You have 3 options to install gREST: | ||
|
||
## Install Using Binary Package | ||
|
||
You can use a python package manager (e.g. pip or easy_install) to install the binary package distributed on [Python Package Index (PYPI)](https://pypi.org/project/pygrest/): | ||
|
||
```bash | ||
pip install pygrest | ||
``` | ||
|
||
## Install From Source Codes | ||
|
||
To install from source codes, clone the gREST's repository using git command (which you should have it installed) and then run setup.py: | ||
|
||
```bash | ||
git clone https://github.com/mostafa/grest.git | ||
cd grest | ||
python setup.py install | ||
``` | ||
|
||
## Installation In Edit Mode <sup>(developer-friendly way)</sup> | ||
|
||
If you want to edit the project and fix bugs or add new features, simply clone the repository and then install the package in edit-mode: | ||
|
||
```bash | ||
git clone https://github.com/mostafa/grest.git | ||
cd grest | ||
pip install -e . | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1 +1,96 @@ | ||
# Tutorial | ||
# 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: | ||
|
||
```python | ||
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](http://neomodel.readthedocs.io/en/latest/getting_started.html#definition) syntax. Neomodel is easier to use than other ORMs and drivers. Your `models.py` file would be like this: | ||
|
||
```python | ||
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: | ||
|
||
```python | ||
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: | ||
|
||
```bash | ||
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: | ||
|
||
```bash | ||
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: | ||
```bash | ||
{"user_id":"937a8d5c1a3a4617bea9ff9b2428778a"} | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters