API implementation

Author: mc-slava

API.md

@@ -0,0 +1,96 @@
+# API Endpoints
+
+
+## Tokens
+
+### Create new token
+
+```
+POST http://localhost:5000/api/tokens
+```
+
+Parameters:
+```
+Basic-auth login & password
+```
+
+### Revoke token
+
+```
+DELETE http://localhost:5000/api/tokens
+```
+
+Parameters:
+```
+Basic-auth login & password
+```
+
+## Users
+
+### Get all users
+
+```
+GET http://localhost:5000/api/users
+```
+
+Token required
+
+### Get one user
+
+```
+GET http://localhost:5000/api/users/1
+```
+
+Token required
+
+### Get followers for user
+
+```
+GET http://localhost:5000/api/users/1/followers
+```
+
+Token required
+
+### Get followed for user
+
+```
+GET http://localhost:5000/api/users/1/followed
+```
+
+Token required
+
+### Create new user
+
+```
+POST http://localhost:5000/api/users
+```
+
+Token not required
+
+Parameters:
+```
+{
+    "username": "blah",
+    "password": "blah",
+    "email": "[email protected]",
+    "about_me": "cool guy"
+}
+```
+
+### Update user
+
+```
+PUT http://localhost:5000/api/users/1
+```
+
+Token required
+
+Parameters:
+```
+{
+    "username": "blah",
+    "password": "blah",
+    "email": "[email protected]",
+    "about_me": "cool guy"
+}
+```

app/__init__.py

@@ -52,6 +52,9 @@ def create_app(config_class=Config):
     from app.auth import bp as auth_bp
     app.register_blueprint(auth_bp, url_prefix='/auth')
 
+    from app.api import bp as api_bp
+    app.register_blueprint(api_bp, url_prefix='/api')
+
     from app.main import bp as main_bp
     app.register_blueprint(main_bp)
 

app/api/__init__.py

@@ -0,0 +1,5 @@
+from flask import Blueprint
+
+bp = Blueprint('api', __name__)
+
+from app.api import users, errors, tokens

app/api/auth.py

@@ -0,0 +1,28 @@
+from flask import g
+from flask_httpauth import HTTPBasicAuth, HTTPTokenAuth
+from app.models import User
+from app.api.errors import error_response
+
+basic_auth = HTTPBasicAuth()
+token_auth = HTTPTokenAuth()
+
+@basic_auth.verify_password
+def verify_password(username, password):
+    user = User.query.filter_by(username=username).first()
+    if user is None:
+        return False
+    g.current_user = user
+    return user.check_password(password)
+
+@basic_auth.error_handler
+def basic_auth_error():
+    return error_response(401)
+
+@token_auth.verify_token
+def verify_token(token):
+    g.current_user = User.check_token(token) if token else None
+    return g.current_user is not None
+
+@token_auth.error_handler
+def token_auth_error():
+    return error_response(401)

app/api/errors.py

@@ -0,0 +1,13 @@
+from flask import jsonify
+from werkzeug.http import HTTP_STATUS_CODES
+
+def error_response(status_code, message=None):
+    payload = {'error': HTTP_STATUS_CODES.get(status_code, 'Unknown error')}
+    if message:
+        payload['message'] = message
+    response = jsonify(payload)
+    response.status_code = status_code
+    return response
+
+def bad_request(message):
+    return error_response(400, message)

app/api/tokens.py

@@ -0,0 +1,32 @@
+from flask import jsonify, g
+from app import db
+from app.api import bp
+from app.api.auth import basic_auth, token_auth
+from app.api.errors import error_response
+from flask_httpauth import HTTPTokenAuth
+from app.models import User
+
+token_auth = HTTPTokenAuth()
+
+@bp.route('/tokens', methods=['POST'])
+@basic_auth.login_required
+def get_token():
+    token = g.current_user.get_token()
+    db.session.commit()
+    return jsonify({'token': token})
+
+@token_auth.verify_token
+def verify_token(token):
+    g.current_user = User.check_token(token) if token else None
+    return g.current_user is not None
+
+@token_auth.error_handler
+def token_auth_error():
+    return error_response(401)
+
+@bp.route('/tokens', methods=['DELETE'])
+@token_auth.login_required
+def revoke_token():
+    g.current_user.revoke_token()
+    db.session.commit()
+    return '', 204

app/api/users.py

@@ -0,0 +1,72 @@
+from app import db
+from app.api import bp
+from app.api.errors import bad_request
+from app.api.auth import token_auth
+from flask import jsonify, request, url_for
+from app.models import User
+
+@bp.route('/users/<int:id>', methods=['GET'])
+@token_auth.login_required
+def get_user(id):
+    return jsonify(User.query.get_or_404(id).to_dict())
+
+@bp.route('/users', methods=['GET'])
+@token_auth.login_required
+def get_users():
+    page = request.args.get('page', 1, type=int)
+    per_page = min(request.args.get('per_page', 10, type=int), 100)
+    data = User.to_collection_dict(User.query, page, per_page, 'api.get_users')
+    return jsonify(data)
+
+@bp.route('/users/<int:id>/followers', methods=['GET'])
+@token_auth.login_required
+def get_followers(id):
+    user = User.query.get_or_404(id)
+    page = request.args.get('page', 1, type=int)
+    per_page = min(request.args.get('per_page', 10, type=int), 100)
+    data = User.to_collection_dict(user.followers, page, per_page,
+                                   'api.get_followers', id=id)
+    return jsonify(data)
+
+@bp.route('/users/<int:id>/followed', methods=['GET'])
+@token_auth.login_required
+def get_followed(id):
+    user = User.query.get_or_404(id)
+    page = request.args.get('page', 1, type=int)
+    per_page = min(request.args.get('per_page', 10, type=int), 100)
+    data = User.to_collection_dict(user.followed, page, per_page,
+                                   'api.get_followed', id=id)
+    return jsonify(data)
+
+@bp.route('/users', methods=['POST'])
+def create_user():
+    data = request.get_json() or {}
+    if 'username' not in data or 'email' not in data or 'password' not in data:
+        return bad_request('must include username, email and password fields')
+    if User.query.filter_by(username=data['username']).first():
+        return bad_request('please use a different username')
+    if User.query.filter_by(email=data['email']).first():
+        return bad_request('please use a different email address')
+    user = User()
+    user.from_dict(data, new_user=True)
+    db.session.add(user)
+    db.session.commit()
+    response = jsonify(user.to_dict())
+    response.status_code = 201
+    response.headers['Location'] = url_for('api.get_user', id=user.id)
+    return response
+
+@bp.route('/users/<int:id>', methods=['PUT'])
+@token_auth.login_required
+def update_user(id):
+    user = User.query.get_or_404(id)
+    data = request.get_json() or {}
+    if 'username' in data and data['username'] != user.username and \
+            User.query.filter_by(username=data['username']).first():
+        return bad_request('please use a different username')
+    if 'email' in data and data['email'] != user.email and \
+            User.query.filter_by(email=data['email']).first():
+        return bad_request('please use a different email address')
+    user.from_dict(data, new_user=False)
+    db.session.commit()
+    return jsonify(user.to_dict())

app/errors/handlers.py

@@ -1,12 +1,21 @@
-from flask import render_template, current_app
+from flask import render_template, request
 from app import db
 from app.errors import bp
+from app.api.errors import error_response as api_error_response
+
+def wants_json_response():
+    return request.accept_mimetypes['application/json'] >= \
+        request.accept_mimetypes['text/html']
 
 @bp.app_errorhandler(404)
 def not_found_error(error):
-    return render_template("errors/404.html", error=error), 404
+    if wants_json_response():
+        return api_error_response(404)
+    return render_template('errors/404.html'), 404
 
 @bp.app_errorhandler(500)
 def internal_error(error):
     db.session.rollback()
-    return render_template("errors/500.html", error=error), 500
+    if wants_json_response():
+        return api_error_response(500)
+    return render_template('errors/500.html'), 500