init

Author: tomasrasymas

.gitignore

@@ -0,0 +1,7 @@
+.DS_Store
+.ipynb_checkpoints
+__pycache__
+.idea
+*.pyc
+/dist/
+/*.egg-info

README.md

@@ -0,0 +1,169 @@
+# Flask-RESTful API project template
+
+This project shows one of the possible ways to implement RESTful API server.
+
+There are implemented two models: User and Todo, one user has many todos.
+
+Main libraries used:
+1. Flask-Migrate - for handling all database migrations.
+2. Flask-RESTful - restful API library.
+3. Flask-Script - provides support for writing external scripts.
+4. Flask-SQLAlchemy - adds support for SQLAlchemy ORM.
+
+Project structure:
+```
+.
+├── README.md
+├── app.py
+├── endpoints
+│   ├── __init__.py
+│   ├── todos
+│   │   ├── __init__.py
+│   │   ├── model.py
+│   │   └── resource.py
+│   └── users
+│       ├── __init__.py
+│       ├── model.py
+│       └── resource.py
+├── manage.py
+├── requirements.txt
+└── settings.py
+```
+
+* endpoints - holds all endpoints.
+* app.py - flask application initialization.
+* settings.py - all global app settings.
+* manage.py - script for managing application (migrations, server execution, etc.)
+
+## Running 
+
+1. Clone repository.
+2. pip install requirements.txt
+3. Run following commands:
+    1. python manage.py db init
+    2. python manage.py db migrate
+    3. python manage.py db upgrade
+4. Start server by running python manage.py runserver
+
+## Usage
+### Users endpoint
+POST http://127.0.0.1:5000/api/users
+
+REQUEST
+```json
+{
+	"name": "John John"
+}
+```
+RESPONSE
+```json
+{
+    "id": 1,
+    "name": "John John",
+    "todos": []
+}
+```
+PUT http://127.0.0.1:5000/api/users/1
+
+REQUEST
+```json
+{
+	"name": "Smith Smith"
+}
+```
+RESPONSE
+```json
+{
+    "id": 1,
+    "name": "Smith Smith",
+    "todos": []
+}
+```
+DELETE http://127.0.0.1:5000/api/users/1
+
+RESPONSE
+```json
+{
+    "id": 3,
+    "name": "Tom Tom",
+    "todos": []
+}
+```
+GET http://127.0.0.1:5000/api/users
+
+RESPONSE
+```json
+{
+    "count": 2,
+    "users": [
+        {
+            "id": 1,
+            "name": "John John",
+            "todos": [
+                {
+                    "id": 1,
+                    "name": "First task",
+                    "description": "First task description"
+                },
+                {
+                    "id": 2,
+                    "name": "Second task",
+                    "description": "Second task description"
+                }
+            ]
+        },
+        {
+            "id": 2,
+            "name": "Smith Smith",
+            "todos": []
+        }
+    ]
+}
+```
+GET http://127.0.0.1:5000/api/users/2
+```json
+{
+    "id": 2,
+    "name": "Smith Smith",
+    "todos": []
+}
+```
+GET http://127.0.0.1:5000/api/users?name=John John
+```json
+{
+    "count": 1,
+    "users": [
+        {
+            "id": 1,
+            "name": "John John",
+            "todos": [
+                {
+                    "id": 1,
+                    "name": "First task",
+                    "description": "First task description"
+                },
+                {
+                    "id": 2,
+                    "name": "Second task",
+                    "description": "Second task description"
+                }
+            ]
+        }
+    ]
+}
+```
+GET http://127.0.0.1:5000/api/users?limit=1&offset=1
+```json
+{
+    "count": 1,
+    "users": [
+        {
+            "id": 2,
+            "name": "Smith Smith",
+            "todos": []
+        }
+    ]
+}
+```
+
+Todo endpoint is similar to Users endpoint.

app.py

@@ -0,0 +1,37 @@
+from flask import Flask, jsonify
+from flask_restful import Api
+from flask_sqlalchemy import SQLAlchemy
+from werkzeug.exceptions import HTTPException
+from werkzeug.exceptions import default_exceptions
+import settings
+
+app = Flask(__name__)
+
+
+@app.errorhandler(Exception)
+def handle_error(e):
+    code = 500
+    if isinstance(e, HTTPException):
+        code = e.code
+    return jsonify(error=str(e)), code
+
+for ex in default_exceptions:
+    app.register_error_handler(ex, handle_error)
+
+
+app.config['SQLALCHEMY_DATABASE_URI'] = settings.SQLALCHEMY_DATABASE_URI
+app.config['SQLALCHEMY_TRACK_MODIFICATIONS'] = settings.SQLALCHEMY_TRACK_MODIFICATIONS
+app.config['BUNDLE_ERRORS'] = settings.BUNDLE_ERRORS
+
+db = SQLAlchemy(app)
+api = Api(app)
+api.prefix = '/api'
+
+from endpoints.users.resource import UsersResource
+from endpoints.todos.resource import TodosResource
+
+api.add_resource(UsersResource, '/users', '/users/<int:user_id>')
+api.add_resource(TodosResource, '/todos', '/todos/<int:todo_id>')
+
+if __name__ == '__main__':
+    app.run()

endpoints/__init__.py

@@ -0,0 +1,15 @@
+from app import db
+
+
+class Todo(db.Model):
+    __tablename__ = 'todo'
+
+    id = db.Column(db.Integer, primary_key=True)
+    name = db.Column(db.String(20))
+    description = db.Column(db.String(100))
+
+    user_id = db.Column(db.Integer, db.ForeignKey('user.id'),
+                        nullable=False)
+
+    def __repr__(self):
+        return 'Id: {}, name: {}'.format(self.id, self.name)

endpoints/todos/__init__.py

@@ -0,0 +1,84 @@
+from flask_restful import Resource, reqparse, request
+from flask_restful import fields, marshal_with, marshal
+from .model import Todo
+from app import db
+
+todo_fields = {
+    'id': fields.Integer,
+    'name': fields.String,
+    'description': fields.String,
+    'user_id': fields.Integer
+}
+
+todo_list_fields = {
+    'count': fields.Integer,
+    'todos': fields.List(fields.Nested(todo_fields)),
+}
+
+todo_post_parser = reqparse.RequestParser()
+todo_post_parser.add_argument('name', type=str, required=True, location=['json'],
+                              help='name parameter is required')
+todo_post_parser.add_argument('description', type=str, required=True, location=['json'],
+                              help='description parameter is required')
+todo_post_parser.add_argument('user_id', type=int, required=True, location=['json'],
+                              help='user_id parameter is required')
+
+
+class TodosResource(Resource):
+    def get(self, todo_id=None):
+        if todo_id:
+            todo = Todo.query.filter_by(id=todo_id).first()
+            return marshal(todo, todo_fields)
+        else:
+            args = request.args.to_dict()
+            limit = args.get('limit', 0)
+            offset = args.get('offset', 0)
+
+            args.pop('limit', None)
+            args.pop('offset', None)
+
+            todo = Todo.query.filter_by(**args).order_by(Todo.id)
+            if limit:
+                todo = todo.limit(limit)
+
+            if offset:
+                todo = todo.offset(offset)
+
+            todo = todo.all()
+
+            return marshal({
+                'count': len(todo),
+                'todos': [marshal(t, todo_fields) for t in todo]
+            }, todo_list_fields)
+
+    @marshal_with(todo_fields)
+    def post(self):
+        args = todo_post_parser.parse_args()
+
+        todo = Todo(**args)
+        db.session.add(todo)
+        db.session.commit()
+
+        return todo
+
+    @marshal_with(todo_fields)
+    def put(self, todo_id=None):
+        todo = Todo.query.get(todo_id)
+
+        if 'name' in request.json:
+            todo.name = request.json['name']
+
+        if 'description' in request.json:
+            todo.description = request.json['description']
+
+        db.session.commit()
+        return todo
+
+    @marshal_with(todo_fields)
+    def delete(self, todo_id=None):
+        todo = Todo.query.get(todo_id)
+
+        db.session.delete(todo)
+        db.session.commit()
+
+        return todo

endpoints/todos/model.py

@@ -0,0 +1,3 @@
+from flask import Blueprint
+
+users_blueprint = Blueprint('users', __name__)

endpoints/todos/resource.py

@@ -0,0 +1,13 @@
+from app import db
+
+
+class User(db.Model):
+    __tablename__ = 'user'
+
+    id = db.Column(db.Integer, primary_key=True)
+    name = db.Column(db.String(20))
+
+    todos = db.relationship('Todo', backref='user', lazy='select')
+
+    def __repr__(self):
+        return 'Id: {}, name: {}'.format(self.id, self.name)