Flask API – Browsable Web APIs for Flask | Hacker News Reader

Flask API – Browsable Web APIs for Flask

flaskapi.org

171 pointstomchristie48 comments

Why use this and not Flask-RESTful? How is the use case different?

http://flask-restful.readthedocs.org/en/latest/

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.

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!

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.

Perhaps an obvious question, but why do APIs need to be browsable?

They don't need too, but it sure-as-hell improves accessibility & usability.

If you are still asking yourself that question, I strongly recommend you read this book: http://restfulwebapis.com/

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?

That's in the contents of the book.

What about using Swagger[0] with flask-restful-swagger[1]?

[0] https://helloreverb.com/developers/swagger [1] https://github.com/rantav/flask-restful-swagger

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.

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.

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.

even better one http://python-eve.org/

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.

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?

> 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.

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...

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

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.

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-w...

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?

> 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?

> Is there a special "API key" for your web app?

And if there is, what's the point? Would the only reason to ever change that key be to force old clients to upgrade if the API changes?

Built in pagination isn't something that's planned atm, tho typically I'd always return objects as the top level representation, and embed the pagination links inside that.

> one example returns json array, what about JSON venerability?

Side point: I don't have a reference for this, but from what I understand the JSON array vulnerability has long since been closed in all sane browsers.

You should check out eve (http://python-eve.org) - it's amazing for rapid prototyping (if the fact it requires Mongo isn't an issue).

I'm building an AngularJS + REST server using Eve for the server. It has saved me so much time that I'm putting my dev effort mainly into a comprehensive test suite because there's so little dev work to do (btw - I'm not the author, it's just the fastest framework I've found for developing REST APIs - and I've tried Django REST framework & tastypie).

Quite an endorsement; I'll have to try to make the time to check that out properly. :)

RE: Eve requiring Mongo, according to slide s 57-61 at https://speakerdeck.com/nicola/eve-rest-api-for-humans Eve supports pluggable backends - is Mongo really needed?

I think the architecture supports pluggable backends, but AFAIK mongo is the best supported (and is the only one I know much about). There is a backend for elasticsearch (https://github.com/petrjasek/eve-elastic) but I've never used it and don't know how complete it is. From looking on github support for SQLAlchemy is slowly in the works.

it seems is pretty much the same as Sails in Node world

I'm considering also Sandman https://github.com/jeffknupp/sandman

wondering how Eve stacks up to that. Sandman you just connect it to the DB and it's supposed to give you a REST api

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.

Looks like this generates HTML-friendly documentation on your Flask routes automatically.

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

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.

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

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).

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).

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.

How does this compare to Eve? [1]

[1] http://python-eve.org/

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

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?

The main site is at: 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.

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

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.

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

Awesome

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!

> 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. :)

Reply on news.ycombinator.com