6 ms·

Flask API – Browsable Web APIs for Flask

171 points by tomchristie 13y ago

glimcat 13y ago
Why use this and not Flask-RESTful? How is the use case different? http://flask-restful.readthedocs.org/en/latest/ http://flask-restful.readthedocs.org/en/latest/
- tomchristie 13y ago
  The most obvious feature difference is the browsable API. Flask API also shares the same architecture as the core of Django REST framework, which I think just has a really nice separation of concerns. Also the interface of `request.data` means is easy to transparently support both JSON and form requests, and the nice content negotiation on responses means it's easy to build services that power both an HTML front-end and an API from the same endpoints. Right now Flask RESTful is more mature of course, but I've got high hopes for this, and it's been super fun to build so far.
  - pmdarrow 13y ago
    We've been considering "porting" our app from Flask-RESTful to Django REST Framework because it is so well architected, tested, and has a large community around it. So I'm overjoyed to hear that you're bringing this awesomeness to the Flask world Tom!
    - tomchristie 13y ago
      Most welcome! For anyone on this thread who's interested in contributing I'd suggest opening a ticket citing your interest, so that we've then go a place we can start the discussion from.
  - rajbala 13y ago
    Perhaps an obvious question, but why do APIs need to be browsable?
    - tomchristie 13y ago
      They don't need too, but it sure-as-hell improves accessibility & usability.
    - jvehent 13y ago
      If you are still asking yourself that question, I strongly recommend you read this book: http://restfulwebapis.com/ http://restfulwebapis.com/
      - rajbala 13y ago
        It's a legitimate question. I understand why URLs need to be browsable. How does a browsable API work when it may need certain HTTP headers, request signatures, etc?
        steveklabnik 13y ago
        That's in the contents of the book.
  - mwhite 13y ago
    What about using Swagger[0] with flask-restful-swagger[1]? [0] https://helloreverb.com/developers/swagger https://helloreverb.com/developers/swagger [1] https://github.com/rantav/flask-restful-swagger https://github.com/rantav/flask-restful-swagger
  - frio 13y ago
    The only reason I still use Django is my deep-seated and abiding love for django-rest-framework. If you're bringing it to Flask, then that's the final bullet.
- pmdarrow 13y ago
  I can sort of comment on this since I've used Flask-RESTful and Django REST Framework where a lot of the Flask-API design is/will be borrowed from. I think the browsable API feature is great but it's not the killer feature for me. To me the killer feature is the well-designed serialization and validation architecture. In Flask-RESTful this seems half-baked - there is no notion of hyperlinked references or nested objects. At our company we ended up implementing our own serialization & validation layer which felt a lot like reinventing the wheel. My hope is that we can bring this same great architecture over from DRF to Flask-API.
- weixiyen 13y ago
  Honestly, Flask-Restful provides almost nothing useful that couldn't be added to an entire Flask project with a few lines of code. I've completely moved away from it as it actually introduced an obscure bug in content negotiation, while at the same time requiring extra mental overhead just to use.
- ciokan 13y ago
  even better one http://python-eve.org/ http://python-eve.org/
kfk 13y ago
Token auth in flask is something I was going to work on soon. It should be straightforward to use a decorator to protect restricted pages. One thing I am absolutely not clear yet is how you keep the user logged if the token expires after x seconds. I mean, if the user is using the app, somehow the token expiring date should be constantly updated, right? All this would be amazing coupled with angularjs… Edit Oh, and I join the question: what about flask-restful?
- tomchristie 13y ago
  > It should be straightforward to use a decorator to protect restricted pages. Authentication policies will use a similar style to the renderers and parsers (and all of REST framework). You'll be able to set them per-view with a decorator, or set them system-wide in the config. You'll also be able to support multiple authentication policies.
  - lukasm 13y ago
    Long story short - I went full hipster on that grunt + yeoman + bower + angular ui and my conclusion is http://i3.kym-cdn.com/photos/images/newsfeed/000/439/835/47c.jpg http://i3.kym-cdn.com/photos/images/newsfeed/000/439/835/47c... Too much complexity added to project. Going REST patch is problematic when you have to integrate with with server-render style lib or service. SEO is shit. Angular doc is worse. Auth is base on tokens, no sessions. I reused the ideas from here https://github.com/mrgamer/angular-login-example https://github.com/mrgamer/angular-login-example def auth_required(f): @wraps(f) def wrapper(args, *kwargs): token = request.headers.get("X-Token") if token is None: abort(400) user = User.verify_auth_token(token, app.config["SECRET_KEY"]) If you don't make very heavy SPA like photoshop, don't use angular.
- hughes 13y ago
  I use Miguel Grinberg's "Token Based Authentication" example[1]. It's based on itsdangerous's TimedJSONWebSignatureSerializer class and it works very well in practice. [1] http://blog.miguelgrinberg.com/post/restful-authentication-with-flask http://blog.miguelgrinberg.com/post/restful-authentication-w...
odonnellryan 13y ago
This is cool. Flask is awesome for Web APIs in general. Either rolling your own, using this, or Flask RESTful.
vosper 13y ago
This looks like a great start, although at the moment it seems to be on-par feature-wise with flask-restful, which is also quite a nice project. I expect the biggest challenges will be integrating authentication and authorization like Django REST Framework has out-of-the-box - Flask has a dearth of packages in this area [1] Keep it up OP, I'm interested to see how this progresses and I'll be following on github. [1] flask-login and flask-principal come to mind, though they still require a writing a lot of code (especially flask-principal).
ermintrude 13y ago
Maybe you could contribute to Eve (http://python-eve.org http://python-eve.org) instead (which is awesome) and already includes some of the features on your roadmap.
- tomchristie 13y ago
  Looks nice. I am considering factoring the core of both Flask API and Django REST framework out into a library that could be integrated with any Python web framework - But that's not going to happen right away, so probably not much use to you in the immediate future. Flask API is pretty simple tho - so there might be bits you can borrow from - perhaps the content negotiation implementation, browsable API implementation, or some of the general API style/separation of concerns that Flask API and Django REST framework both share. The big win would be having more than one project sharing the same APIs for renderers, parsers, authentication, permissions and throttling policies - that way there'd be scope for writing at least some libraries that work cross-framework.
  - codygman 13y ago
    Like how django-social-auth turned into python-social-auth? Framework agnostic libraries is one of the reasons Haskell has had me smitten for quite a while now
sophacles 13y ago
Request to the authors: This project looks really cool, I can see myself using it soon. Please though be careful with your auth stuff, that is where things get tricky in terms of integrating other plugins and whatnot. I'm not sure how you'll go about it, but it will probably be awesome if you keep flexibility and plugability with the flask ecosystem in mind.
nebstrebor 13y ago
Great work, Tom! And timely. Django-rest-framework is #1 on my list of the best Django packages out there. I was about to start an API project in Flask, but was thinking that I'd really really miss DRF and its great architecture adn features (powerful out of the box, everything easily overridable, great separation of concerns, and browsable API).
jnbiche 13y ago
Excellent work! Oh, the times I've wished for something like Django REST Framework in Flask but was too busy and/or lazy to implement it myself. Thank you! For those unfamiliar with Django REST Framework, please go take a look. One of the few, perhaps the only, web framework to take all (or maybe almost all) of Fielding's ideas behind REST seriously. This is more than just theoretical -- once you've created a client application that takes full advantage of a HATEOAS API, you'll understand that it's much more than an annoying acronym.
sscgod 13y ago
Awesome
notastartup 13y ago
Absolutely amazing stuff been looking for something like django rest framework on Flask. Any dates for 1.0 release? I'm looking forward to the authentication and such. What would be great is also some implementation of Sandman's auto inspection of database to create REST api, with support for One to Many, Many to Many relationships. Great job!
- tomchristie 13y ago
  > Any dates for 1.0 release? If anyone wants to give me a coupla days paid work on this, then yah I'm sure that could be arranged. :)
antihero 13y ago
Oh fantastic! I love Django REST but have wanted the speed of something more lightweight for a while.
lukasm 13y ago
I spent last 3 months building AngularJS + Flask where the client talks to server only through REST. There were 3 options: 1. Bare Flask 2. Flask RESTful 3. Flask Restless I've spent quite some time investigating 2nd and 3rd options. Problems with 2nd: a) Didn't bring much to the table comparing to pure Flask. Extra abstraction and complexity that without much improvements b) Swallowing Flask exceptions c) Risk that the project will be abandoned and poor maintenance (commit frequency) 3rd: Direct mapping to SQL-Alchemy models is too restrict. Hard to change stuff - very opinionated I end up with pure Flask. It's already good with enough rest framework!. Great balance between power and abstraction. I'm looking forward to dig into this project. Would be great if it has great integration with flask admin and security. Also support for OAuth flows would be awesome. I have a few question for the author - of top of my head. How do you handle pagination? one example returns json array, what about JSON vulnerability?
- emillon 13y ago
  > I spent last 3 months building AngularJS + Flask where the client talks to server only through REST. I've been wanting to do something like this for a certain time, so I have a few questions if you don't mind. How do you handle authentication? Tokens? Cookies? Is there a special "API key" for your web app?
  - lukasm 13y ago
    Long story short - I went full hipster on that grunt + yeoman + bower + angular ui and my conclusion is http://i3.kym-cdn.com/photos/images/newsfeed/000/439/835/47c.jpg http://i3.kym-cdn.com/photos/images/newsfeed/000/439/835/47c... Too much complexity added to project. Going REST patch is problematic when you have to integrate with server-render style lib or service. SEO is shit. Angular doc is worse. Auth is base on tokens, no sessions. I reused the ideas from here https://github.com/mrgamer/angular-login-example https://github.com/mrgamer/angular-login-example def auth_required(f): @wraps(f) def wrapper(*args, **kwargs): token = request.headers.get("X-Token") if token is None: abort(400) user = User.verify_auth_token(token, app.config["SECRET_KEY"]) .... If you don't make very heavy SPA like photoshop, don't use angular.
  - 13y ago
bliti 13y ago
I was about to write the same thing. Thank you for taking the time to do this. It is exactly what I needed to build APIs at Mokriya.
mbreese 13y ago
Can someone tell me the advantages of all of these extra extensions for Flask? I thought the point of Flask was to make the framework part extremely light-weight. When I need a REST-ful API for a Flask app, I just build the routes needed and code it up myself. Why both adding a whole extra framework for something? Flask by itself is already capable of supporting REST-style requests, so what does this do again? How much of the example listed was ordinary Flask-webapp code and how much was this extension? Add an HTML view to a JSON object and form for making REST requests? Between this and the User extension from last night, I must be missing something. Or maybe I'm just old.
- brown9-2 13y ago
  Looks like this generates HTML-friendly documentation on your Flask routes automatically.
stevewilhelm 13y ago
How does this compare to Eve? [1] [1] http://python-eve.org/ http://python-eve.org/
frodopwns 13y ago
I use Python Eve. Pretty good Restful API built on Flask.
matthuggins 13y ago
Went to the site hoping to learn what Flask is, but they don't even link to it anywhere. Doing a Google search for "flask" just returns a bunch of drinking flasks, and flask.com is for buying flasks as well. So great, what is Flask? What is this about?
- mmcclellan 13y ago
  The main site is at: http://flask.pocoo.org/ http://flask.pocoo.org/ Flask is a web framework for Python. It's smaller and lighter than Django, and can be picked up very quickly. Basically, the author of this library has a well-liked REST framework for Django, and folks are excitedg to see this goodness being brought over for Flask.

171 points by tomchristie 13y ago

Why use this and not Flask-RESTful? How is the use case different? http://flask-restful.readthedocs.org/en/latest/ http://flask-restful.readthedocs.org/en/latest/

tomchristie 13y ago
The most obvious feature difference is the browsable API. Flask API also shares the same architecture as the core of Django REST framework, which I think just has a really nice separation of concerns. Also the interface of `request.data` means is easy to transparently support both JSON and form requests, and the nice content negotiation on responses means it's easy to build services that power both an HTML front-end and an API from the same endpoints. Right now Flask RESTful is more mature of course, but I've got high hopes for this, and it's been super fun to build so far.
- pmdarrow 13y ago
  We've been considering "porting" our app from Flask-RESTful to Django REST Framework because it is so well architected, tested, and has a large community around it. So I'm overjoyed to hear that you're bringing this awesomeness to the Flask world Tom!
  - tomchristie 13y ago
    Most welcome! For anyone on this thread who's interested in contributing I'd suggest opening a ticket citing your interest, so that we've then go a place we can start the discussion from.
- rajbala 13y ago
  Perhaps an obvious question, but why do APIs need to be browsable?
  - tomchristie 13y ago
    They don't need too, but it sure-as-hell improves accessibility & usability.
  - jvehent 13y ago
    If you are still asking yourself that question, I strongly recommend you read this book: http://restfulwebapis.com/ http://restfulwebapis.com/
    - rajbala 13y ago
      It's a legitimate question. I understand why URLs need to be browsable. How does a browsable API work when it may need certain HTTP headers, request signatures, etc?
      - steveklabnik 13y ago
        That's in the contents of the book.
- mwhite 13y ago
  What about using Swagger[0] with flask-restful-swagger[1]? [0] https://helloreverb.com/developers/swagger https://helloreverb.com/developers/swagger [1] https://github.com/rantav/flask-restful-swagger https://github.com/rantav/flask-restful-swagger
- frio 13y ago
  The only reason I still use Django is my deep-seated and abiding love for django-rest-framework. If you're bringing it to Flask, then that's the final bullet.
pmdarrow 13y ago
I can sort of comment on this since I've used Flask-RESTful and Django REST Framework where a lot of the Flask-API design is/will be borrowed from. I think the browsable API feature is great but it's not the killer feature for me. To me the killer feature is the well-designed serialization and validation architecture. In Flask-RESTful this seems half-baked - there is no notion of hyperlinked references or nested objects. At our company we ended up implementing our own serialization & validation layer which felt a lot like reinventing the wheel. My hope is that we can bring this same great architecture over from DRF to Flask-API.
weixiyen 13y ago
Honestly, Flask-Restful provides almost nothing useful that couldn't be added to an entire Flask project with a few lines of code. I've completely moved away from it as it actually introduced an obscure bug in content negotiation, while at the same time requiring extra mental overhead just to use.
ciokan 13y ago
even better one http://python-eve.org/ http://python-eve.org/

kfk 13y ago

Token auth in flask is something I was going to work on soon. It should be straightforward to use a decorator to protect restricted pages. One thing I am absolutely not clear yet is how you keep the user logged if the token expires after x seconds. I mean, if the user is using the app, somehow the token expiring date should be constantly updated, right? All this would be amazing coupled with angularjs… Edit Oh, and I join the question: what about flask-restful?

tomchristie 13y ago
> It should be straightforward to use a decorator to protect restricted pages. Authentication policies will use a similar style to the renderers and parsers (and all of REST framework). You'll be able to set them per-view with a decorator, or set them system-wide in the config. You'll also be able to support multiple authentication policies.
- lukasm 13y ago
  Long story short - I went full hipster on that grunt + yeoman + bower + angular ui and my conclusion is http://i3.kym-cdn.com/photos/images/newsfeed/000/439/835/47c.jpg http://i3.kym-cdn.com/photos/images/newsfeed/000/439/835/47c... Too much complexity added to project. Going REST patch is problematic when you have to integrate with with server-render style lib or service. SEO is shit. Angular doc is worse. Auth is base on tokens, no sessions. I reused the ideas from here https://github.com/mrgamer/angular-login-example https://github.com/mrgamer/angular-login-example def auth_required(f): @wraps(f) def wrapper(args, *kwargs): token = request.headers.get("X-Token") if token is None: abort(400) user = User.verify_auth_token(token, app.config["SECRET_KEY"]) If you don't make very heavy SPA like photoshop, don't use angular.
hughes 13y ago
I use Miguel Grinberg's "Token Based Authentication" example[1]. It's based on itsdangerous's TimedJSONWebSignatureSerializer class and it works very well in practice. [1] http://blog.miguelgrinberg.com/post/restful-authentication-with-flask http://blog.miguelgrinberg.com/post/restful-authentication-w...

odonnellryan 13y ago

This is cool. Flask is awesome for Web APIs in general. Either rolling your own, using this, or Flask RESTful.

vosper 13y ago

This looks like a great start, although at the moment it seems to be on-par feature-wise with flask-restful, which is also quite a nice project. I expect the biggest challenges will be integrating authentication and authorization like Django REST Framework has out-of-the-box - Flask has a dearth of packages in this area [1] Keep it up OP, I'm interested to see how this progresses and I'll be following on github. [1] flask-login and flask-principal come to mind, though they still require a writing a lot of code (especially flask-principal).

ermintrude 13y ago

Maybe you could contribute to Eve (http://python-eve.org http://python-eve.org) instead (which is awesome) and already includes some of the features on your roadmap.

tomchristie 13y ago
Looks nice. I am considering factoring the core of both Flask API and Django REST framework out into a library that could be integrated with any Python web framework - But that's not going to happen right away, so probably not much use to you in the immediate future. Flask API is pretty simple tho - so there might be bits you can borrow from - perhaps the content negotiation implementation, browsable API implementation, or some of the general API style/separation of concerns that Flask API and Django REST framework both share. The big win would be having more than one project sharing the same APIs for renderers, parsers, authentication, permissions and throttling policies - that way there'd be scope for writing at least some libraries that work cross-framework.
- codygman 13y ago
  Like how django-social-auth turned into python-social-auth? Framework agnostic libraries is one of the reasons Haskell has had me smitten for quite a while now

sophacles 13y ago

Request to the authors: This project looks really cool, I can see myself using it soon. Please though be careful with your auth stuff, that is where things get tricky in terms of integrating other plugins and whatnot. I'm not sure how you'll go about it, but it will probably be awesome if you keep flexibility and plugability with the flask ecosystem in mind.

nebstrebor 13y ago

Great work, Tom! And timely. Django-rest-framework is #1 on my list of the best Django packages out there. I was about to start an API project in Flask, but was thinking that I'd really really miss DRF and its great architecture adn features (powerful out of the box, everything easily overridable, great separation of concerns, and browsable API).

jnbiche 13y ago

Excellent work! Oh, the times I've wished for something like Django REST Framework in Flask but was too busy and/or lazy to implement it myself. Thank you! For those unfamiliar with Django REST Framework, please go take a look. One of the few, perhaps the only, web framework to take all (or maybe almost all) of Fielding's ideas behind REST seriously. This is more than just theoretical -- once you've created a client application that takes full advantage of a HATEOAS API, you'll understand that it's much more than an annoying acronym.

sscgod 13y ago

Awesome

notastartup 13y ago

Absolutely amazing stuff been looking for something like django rest framework on Flask. Any dates for 1.0 release? I'm looking forward to the authentication and such. What would be great is also some implementation of Sandman's auto inspection of database to create REST api, with support for One to Many, Many to Many relationships. Great job!

tomchristie 13y ago
> Any dates for 1.0 release? If anyone wants to give me a coupla days paid work on this, then yah I'm sure that could be arranged. :)

antihero 13y ago

Oh fantastic! I love Django REST but have wanted the speed of something more lightweight for a while.

lukasm 13y ago

I spent last 3 months building AngularJS + Flask where the client talks to server only through REST. There were 3 options: 1. Bare Flask 2. Flask RESTful 3. Flask Restless I've spent quite some time investigating 2nd and 3rd options. Problems with 2nd: a) Didn't bring much to the table comparing to pure Flask. Extra abstraction and complexity that without much improvements b) Swallowing Flask exceptions c) Risk that the project will be abandoned and poor maintenance (commit frequency) 3rd: Direct mapping to SQL-Alchemy models is too restrict. Hard to change stuff - very opinionated I end up with pure Flask. It's already good with enough rest framework!. Great balance between power and abstraction. I'm looking forward to dig into this project. Would be great if it has great integration with flask admin and security. Also support for OAuth flows would be awesome. I have a few question for the author - of top of my head. How do you handle pagination? one example returns json array, what about JSON vulnerability?

emillon 13y ago
> I spent last 3 months building AngularJS + Flask where the client talks to server only through REST. I've been wanting to do something like this for a certain time, so I have a few questions if you don't mind. How do you handle authentication? Tokens? Cookies? Is there a special "API key" for your web app?
- lukasm 13y ago
  Long story short - I went full hipster on that grunt + yeoman + bower + angular ui and my conclusion is http://i3.kym-cdn.com/photos/images/newsfeed/000/439/835/47c.jpg http://i3.kym-cdn.com/photos/images/newsfeed/000/439/835/47c... Too much complexity added to project. Going REST patch is problematic when you have to integrate with server-render style lib or service. SEO is shit. Angular doc is worse. Auth is base on tokens, no sessions. I reused the ideas from here https://github.com/mrgamer/angular-login-example https://github.com/mrgamer/angular-login-example def auth_required(f): @wraps(f) def wrapper(*args, **kwargs): token = request.headers.get("X-Token") if token is None: abort(400) user = User.verify_auth_token(token, app.config["SECRET_KEY"]) .... If you don't make very heavy SPA like photoshop, don't use angular.
- 13y ago

bliti 13y ago

I was about to write the same thing. Thank you for taking the time to do this. It is exactly what I needed to build APIs at Mokriya.

mbreese 13y ago

Can someone tell me the advantages of all of these extra extensions for Flask? I thought the point of Flask was to make the framework part extremely light-weight. When I need a REST-ful API for a Flask app, I just build the routes needed and code it up myself. Why both adding a whole extra framework for something? Flask by itself is already capable of supporting REST-style requests, so what does this do again? How much of the example listed was ordinary Flask-webapp code and how much was this extension? Add an HTML view to a JSON object and form for making REST requests? Between this and the User extension from last night, I must be missing something. Or maybe I'm just old.

brown9-2 13y ago
Looks like this generates HTML-friendly documentation on your Flask routes automatically.

stevewilhelm 13y ago

How does this compare to Eve? [1] [1] http://python-eve.org/ http://python-eve.org/

frodopwns 13y ago

I use Python Eve. Pretty good Restful API built on Flask.

matthuggins 13y ago

Went to the site hoping to learn what Flask is, but they don't even link to it anywhere. Doing a Google search for "flask" just returns a bunch of drinking flasks, and flask.com is for buying flasks as well. So great, what is Flask? What is this about?

mmcclellan 13y ago
The main site is at: http://flask.pocoo.org/ http://flask.pocoo.org/ Flask is a web framework for Python. It's smaller and lighter than Django, and can be picked up very quickly. Basically, the author of this library has a well-liked REST framework for Django, and folks are excitedg to see this goodness being brought over for Flask.