Designing a RESTful API using Flask-RESTful

your tutorials are really awesome.. they have been the bone of my progress in flask.
pls can you add links to the 2 preceding articles about creating restful apps with flask.

Thanks :)

Hi Miguel,

FYI

I started going through the Flask-RESTful docs and noticed that they are deprecating the RequestParser and thought I would pass that along. https://flask-restful.readthedocs.io/en/latest/reqparse.html#request-parsing

Bob

ps Loved your Oreilly video on Building Web APIs with Flask

Hello Miguel,
Thanks for great guidelines. Just want to find out in your restful v2, the uri is "/todo/api/v1.0/tasks/[task_id]" only, instead of full url "http://[hostname]/todo/api/v1.0/tasks/[task_id]" compare to v1, what is the point here?

Thank you very much!

@Tuan: this is because the URLs in this example are generated by Flask-RESTful, which by default generates relative URLs. You can switch to absolute URLs if you change fields.Url('task') to 'uri': fields.Url('task', absolute=True).

Thanks Miguel. The API is working as expected but if i supervise data packets by tcpdump/wireshark, it always show "Malformed Packet" or "Unreassembled Packet" for both request and response, regardless i start the API from pure python command or put it behind nginx + gunicorn. Could you please to take a look?

@Tuan: there are several reasons why wireshark may have trouble decoding packets, all unrelated to the application, which works at a much higher level. See the documentation at https://www.wireshark.org/docs/wsug_html_chunked/AppMessages.html.

Hello Miguel and thanks for the awsome education material in particular for a beginner in python/flask.

I've been working on connecting the flask-restful example to a flask-sql-alchemy DB, with very partial success till now (Add Task function works because i see the new task in the DB file).

But otherwise the Task List doesnt seem to reach the client and I am stuck with cryptic trace back like: "werkzeug.routing.BuildError: Could not build url for endpoint 'task' with values ['task']. Did you forget to specify values ['id']?"

*The app is initialized with the original api path:
from resources import TaskListAPI
from resources import TaskAPI

api.add_resource(TaskListAPI, '/todo/api/v1.0/tasks', endpoint='tasks')
api.add_resource(TaskAPI, '/todo/api/v1.0/tasks/<int:id>', endpoint='task')

I suppose the bug is in the API classes functions:
the API classes are:

task_fields = {

'title': fields.String,
'description': fields.String,
'done': fields.Boolean,
'uri': fields.Url('task', absolute=True)

}

class TaskListAPI(Resource):
decorators = [auth.login_required]

def __init__(self):
    self.reqparse = reqparse.RequestParser()
    self.reqparse.add_argument('title', type=str, required=True,
                               help='No task title provided',
                               location='json')
    self.reqparse.add_argument('description', type=str, default="",
                               location='json')
    super(TaskListAPI, self).__init__()

@marshal_with(task_fields)
def get(self):
    tasks = session.query(Task).all()
    return {'tasks': [marshal(task, task_fields) for task in tasks]}

@marshal_with(task_fields)
def post(self):
    parsed_args = self.reqparse.parse_args()
    task = Task(title=parsed_args['title'], description=parsed_args['description'], done=False)
    session.add(task)
    session.commit()
    return {'task': marshal(task, task_fields)}, 201

class TaskAPI(Resource):
decorators = [auth.login_required]

def __init__(self):
    self.reqparse = reqparse.RequestParser()
    self.reqparse.add_argument('title', type=str, location='json')
    self.reqparse.add_argument('description', type=str, location='json')
    self.reqparse.add_argument('done', type=bool, location='json')
    super(TaskAPI, self).__init__()

@marshal_with(task_fields)
def get(self, id):
    task = session.query(Task).filter(Task.id == id).first()
    if not task:
        abort(404, message="Task {} doesn't exist".format(id))
    return {'task': marshal(task[0], task_fields)}

def delete(self, id):
    task = session.query(Task).filter(Task.id == id).first()
    if not task:
        abort(404, message="Task {} doesn't exist".format(id))
    session.delete(task)
    session.commit()
    return {'result': True}

@marshal_with(task_fields)
def put(self, id):
    parsed_args = self.reqparse.parse_args()
    task = session.query(Task).filter(Task.id == id).first()
    task.title = parsed_args['title']
    session.add(task)
    session.commit()
    return {'task': marshal(task, task_fields)}

Any comment , explanation or advise on that thing is welcome :)
What should I do to get it work properly?

@gbarrido: without saying the full stack trace I can't really say. But it looks like you are doing double marshalling in your endpoints, you have the decorator and also calling the marshal function. You have to pick one.

Yes, that was the problem, thanks for pointing it out!

Btw as a more general feedback, the quality of your tuto is imo because they are A to Z, integrating several techniques in one complete, working example, which is extremely useful to kick start for a newbie.

If you ever feel like to apply your didactic talent to other flask-* combinations, here is my wish list (it's soon Xmas afterall :)

• flask-restful API + (flask-)sqlalchemy + Mobile App client (Qt/QML for example)
• flask-restless + (flask-)marshmallow + the awsome knockout client

Thanks again for the efficient feedback and tutorials
gb

Hi,

Can you marry this article with the blueprint-based version handling you defined in this stackoverflow response? http://stackoverflow.com/questions/28795561/support-multiple-api-versions-in-flask

Do you still use the @api.route decorator or is the better approach to use a class name(Resource) combined with api.add_resource?

Thanks,

Gunnar

@Gunnar: api.route decorator is basic Flask. The Resource class is from an extension, Flask-RESTful. Which one to use is really a matter of preference, in the end, the just use different approaches to register your endpoints.

Thanks Miguel. Strangely, I cannot get the example to work.

Traceback (most recent call last):
File "test.py", line 3, in <module>
from api.v1 import api as api_v1
File "/home/gunnar/testapp/test/api/v1/init.py", line 5, in <module>
from . import routes
File "/home/gunnar/testapp/test/api/v1/routes.py", line 8, in <module>
@api.route('/metrics/<string:metric_id>', methods = ['GET', 'PUT'])
NameError: name 'api' is not defined
The project organization is:

test.py
+api/
+-- v1/
+-- init.py
+-- routes.py
init.py contains:

from flask import Blueprint

api = Blueprint( 'api', name )

from . import routes
routes.py contains:

from flask import request
from flask_restful import Resource

metrics = {}

@api.route('/metrics/<string:metric_id>', methods = ['GET', 'PUT'])
def process_metric( metric_id ):
if request.method == 'GET':
return { metric_id: metrics[metric_id] }

if request.method == 'PUT':
   metrics[metric_id] = request.form['data']
   return { metric_id: metrics[metric_id] }

It seems to me that it'd be better(?) to use the class approach but I don't understand how to do that when using blueprints and the versioning scheme?

@Gunnar: you are importing "api' as "api_v1', so you should invoke the decorator as "api_v1.route".

@Miquel

No love.

Traceback (most recent call last):
File "writer.py", line 3, in <module>
from api.v1 import api as api_v1
File "/home/gunnar/testapp/test/api/v1/init.py", line 5, in <module>
from . import routes
File "/home/gunnar/testapp/test/api/v1/routes.py", line 8, in <module>
@api_v1.route('/metrics/<string:metric_id>', methods = ['GET', 'PUT'])
NameError: name 'api_v1' is not defined

@Gunnar: You seem to have cyclic imports. Your writer.py module imports api.v1.api, which in turn imports api.v1.routes, which imports api.v1.api again. Fix the recursive imports and you should be fine. If you don't know how, look up my Flask at Scale class on youtube, I covered this issue near the beginning of that class.

@Miguel. Thanks, I now understand the imports. The routing still doesn't work so I'm missing something.

testapp.py

from flask import Flask
from flask_restful import Api
from api.v1 import api as api_v1

app = Flask(__name__)

app.register_blueprint(api_v1, url_prefix='/v1')

if __name__ == '__main__':
   app.run(debug=True)

./api/v1/init.py:

from flask import Blueprint

api = Blueprint( 'api', __name__ )

./api/v1/routes.py:

from flask import request
from flask_restful import Resource

tests = {}

# api is defined in __init__.py
# @api_v1.route('/test/<string:test_id>', methods = ['GET', 'PUT'])
# def do_test( test_id ):
#     if request.method == 'GET':
#        return { test_id: tests[test_id] }

#     if request.method == 'PUT':
#        tests[test_id] = request.form['data']
#        return { test_id: tests[test_id] }

class TestAPI( Resource ):
   def get( self, test_id ):
       return { test_id: tests[test_id] }

   def put( self, test_id ):
       tests[test_id] = request.form['data']
       return { test_id: tests[test_id] }

api.add_resource( TestAPI, '/test/<string:test_id>' )

I tested both approaches (comment/uncomment as needed.)

python testapp.py
* Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)
* Restarting with stat
* Debugger is active!
* Debugger pin code: 151-213-751
127.0.0.1 - - [30/Nov/2016 22:31:41] "PUT /v1/test/foo HTTP/1.1" 404 -

Request:

$ curl http://localhost:5000/v1/test/foo -d "data=2010-01-01,10,/foo/bar,20" -X PUT
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<title>404 Not Found</title>
<h1>Not Found</h1>
<p>The requested URL was not found on the server.  If you entered the URL manually please check your     spelling and try again.</p>

I'm sorry if I'm missing something obvious here. Hopefully, this discussion will generate a straightforward skeleton once working.

@Gunnar: Looks like you are not importing the routes, so they never get registered with the blueprint. Add a "from . import routes" right below the Blueprint creation line.

@Miguel. As it turns out, the use of blueprint is a bit more involved. Here's a working example:

testapp.py

from flask import Flask
from flask_restful import Api
from api.v1 import api_bp as api_v1

app = Flask(__name__)

app.register_blueprint( api_v1, url_prefix='/v1' )

if __name__ == '__main__':
   app.run(debug=True)

NOTE: Import of blueprint "api_bp" as "api_v1". (This was named "api" in previous examples; "api_bp" seems clearer.)

api/v1/init.py

from flask import Blueprint
from flask_restful import Api

api_bp = Blueprint( 'api', __name__ )
api = Api( api_bp )

from routes import TestAPI
api.add_resource( TestAPI, '/test/<string:test_id>' )

NOTE: Import of class "TestAPI" from api/v1/routes.py. Addition of "api = Api( api_bp)", which is what's required for "api.add_resource".

api/v1/routes.py:

from flask import request
from flask_restful import Resource

tests = {}

class TestAPI( Resource ):
   def get( self, test_id ):
       return { test_id: tests[test_id] }

   def put( self, test_id ):
       tests[test_id] = request.form['data']
       return { test_id: tests[test_id] }

NOTE: I tried to include the routing information in "api/v1/routes.py" but that doesn't work.

Test run:

$ curl http://localhost:5000/v1/test/foo -d "data=Remember the milk" -X PUT
{
    "foo": "Remember the milk"
}

$ curl http://localhost:5000/v1/test/foo
{
    "foo": "Remember the milk"
}

$ python testapp.py
 * Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)
 * Restarting with stat
 * Debugger is active!
 * Debugger pin code: 151-213-751
127.0.0.1 - - [01/Dec/2016 22:21:59] "PUT /v1/test/foo HTTP/1.1" 200 -
127.0.0.1 - - [01/Dec/2016 22:22:01] "GET /v1/test/foo HTTP/1.1" 200 -

I hope this helps anyone who wants to use this cool versioning approach.

Hi Miguel,

thank you for your tutorials!

I just started your O'Reilly Web API video course and ran into the first problem in Chapter "API Demonstrations":

when I do:
http GET http://localhost:5000/customers/

I get:
http: error: ConnectionError: HTTPConnectionPool(host='localhost', port=5000): Max retries exceeded with url: /customers/ (Caused by <class 'ConnectionRefusedError'>: [Errno 61] Connection refused)

can you suggest any way forward?

I have tried with python 3.6 as well as 3.4.4

Should I expect problems with python 3.6.0?

Thank you for your help.

Cheers!

@Ditmr: Did you start the Flask server before sending the request?

Thank you Miguel,

python api.py in second terminal did the trick!

Love the way you explain things, simple and straight forward tutorials.

Hi Miguel, Very nice article. I hope you can create an article that will discuss the details on how we can design the file structure, development and production strategy. I'm relatively new to python and I can simply follow good tutorial. But most tutorials deals on how to code python. But the workflow and file structure of how a good project should look like, that's what I'm really missing.

@Lance: I have written and spoken extensively about Flask project structure. You may want to look at my Flask Web Development book, or the tutorials I gave at the last three PyCons, which are all available on YouTube.

Is it just me or is Flask-RESTful a lot slower than just Flask? I plugged my own data (with more deeply nested and large data) into both versions of the REST API and the Flask-RESTful version is WAY slower (5 sec). Regular Flask version is almost instantaneous response.