Eve: A Python REST API Framework | Hacker News Reader

Eve: A Python REST API Framework

python-eve.org

102 pointsm0th8733 comments

Leaving PUT out might be a mistake. The rationale from the slide deck is sound but the framework neglects the case in which you are creating a resource with a known identifier. The POST verb is good for when you don't know the identifier, and want to leave it up to the handler to generate one for you. You could just define the same semantics for POST as for PUT, but that breaks the spec in that a resource created by POST should be subordinate to the requested resource.

Whatever the URI is, it's still going to be a sub-resource of some collection, right? That's the only way of defining how to stuff it into the DB. I didn't see any way of defining schemata for "one-off" top-level resources. Since these resources are just members of collections, I don't see the problem with using internally-generated identifiers for them.

If you want to allow "/people/12345" to be accessed at "/people/johnson" or even "/johnson", it seems Flask routing would make that trivial. I don't think Eve itself has to care. [EDIT: even so, I see now that "/people/johnson" is possible through "custom item endpoints".]

By the way, I might be in love with this framework.

They give a good rationale for supporting PATCH, but not for omitting PUT. Not supporting PUT is absolutely a mistake, especially with a schema-less backend. Being unable to PUT means being unable to set a property as undefined (by PUTting a complete version of the resource without that property). The usual approach with PATCH is to set it to None/null, but then the property is still defined as None instead of removed. (Or, some APIs will remove a property with a None value, but then it is undefined instead of being set to None.) A small but potentially important semantic distinction.

Does this corner case really justify dealing with another entire verb? Even if we stipulate that null has a specific meaning for our application that we don't want to screw up, how about empty object, array, or string? ( {}, [], or "" ) Do all of those mean something for, e.g., the "lastname" field?

It's not the only reason. PUT is the only way to do retryable creates since it's idempotent. Leaving it out is a huge omission.

PUT is almost functionally identical to a PATCH, so it’s not exactly an entire other verb. It’s also a very standard verb. Using the example from a pull request on Eve ( https://github.com/nicolaiarocci/eve/issues/96 ), what if you want to indicate that the middle name is no longer known? Marking it as null means there isn’t one, not that it is unknown. Sure, for many applications the distinction doesn’t matter. But for plenty, it does. (I just recently had to fix an API’s implementation of PUT that actually was more like a PATCH but needed to be a proper PUT.) And it’s foolish for an API to require knowing a nonstandard way of expressing `undefined` when simply not defining something is the best way to not define it.

Eve looks nice, but they really need to justify not supporting PUT, beyond just “PATCH is usually better”.

Hello, thanks for your feedback. PUT is coming to Eve with v0.1.0 (next release).

In fact, it's on the dev branch already.

Interesting. I've just completed a library to run on Flask. Actually, it's an extension of flask_restful that allows for arbitrary nested resources, control over fields exposed the whole way down the tree etc. PUT/POST of deeply nested objects. I built it because I'm using SQLAlchemy and nothing quite supported how I wanted to do it. I've also used the helpers from flask_restless (with a bunch of modifications) to help with the loading / saving of SQLAlchemy object trees.

Example definition of a resource:

    class JobList(resty.ResourceList):
        model = models.Job
        deep = dict(disciplines=dict(drawings=None))
        query_options = subqueryload_all('disciplines.drawings')

I know have a really easy to configure api that plays very nicely with Restangular. It's very simple - totally not rest complete, but sufficient for my needs.

A simple REST api framework for Python is something I've been looking for, and this definitely fits the bill. Unfortunately, I need to use it with Postgres. For those who also have this requirement, it looks like they have a SQLAlchemy development branch that enables support for relational databases. Looks promising!

This indeed looks promising and lightweight. For relational databases there is always Django Tastypie (although it depends on Django and is heavier than this Flask alternative)

http://tastypieapi.org/

Using Flask, SQLAlchemy what is it that you are missing?

Writing the glue takes a surprising amount of time/energy/learning for a newb. I've got a couple of hobby projects on the go where I am learning to create webapps / rest apis using flask + SQLAlchemy. None of these projects are anywhere near shippable.

Not knocking the tools, they're great + fun. But writing the glue gets non-trivial fast once you step beyond a single table with no access control.

Have you tried Bottle? It is very simple, defined in one file that you include with your project. It has attribute-based routing (including PUT!). It's great for smaller projects and prototyping. I'm not sure how well it scales to larger projects.

Have a look at Spyne: http://spyne.io

Specifically: http://spyne.io/#s=sql&ser=Json&show=Data

Try flask-restful

also Flask-Restless (http://flask-restless.readthedocs.org)

And as usual, this is REST-as-a-buzzword, not REST-as-REpresentational-State-Transfer.

I thought just the opposite. I was pleasantly surprised to see that it looks pretty in line with Fielding's thesis. What are you objecting to?

* Primary focus on URI structure (to the point where the third thing explained is that you can access each resource from multiple URIs… after the URI being customizable and the URI pattern & mapping to CRUD operations). That there are links is only "documented" at #6.

* Very little on document structure: only mentioned in examples, no overview let alone more precise documentation, there seems to be 5 or 6 possible _link keys but none is defined further than the examples showing it exists. Notes that the entry point will be disabled if links are disabled, said entry point's media type is not documented and only defined as "a list of links to accessible resources".

* Very limited linking (only tree traversal/reads), no support at all for resource alteration information in documents, how a resource is created, modified or deleted is solely out-of-band knowledge. No state transition is available to a RESTful Eve client, it is limited to a readonly interface.

* Same for non-trivial fetching, e.g. filter and search

* What little linking there is, is optional (!)

* No custom content types, no media types documentation

* And the official documentation generation extension documents (verb, URI) pairs: http://blog.python-eve.org/eve-docs, what little data documentation there is is subservient to the creation (verb, URI) pair, and is the expected payload...

I rest my case, Eve only puts "emphasis on REST" in the "REST as a meaningless buzzword" sense, no other understanding matches the reality of the documentation.

edit: don't get me wrong, if you want to build a "random stuff over HTTP" or "RPC over HTTP" or "Ad-hoc over HTTP" API it's fine. If it works for you (or does not, I don't really care) nobody's going to mind. Just stop fucking lying about what it is.

Can you point to some examples of REST apis that show what this is missing?

Not necessarily disagreeing but can you point to any real-world REST-as-Master-Fielding-intended API to convince the sceptical among us it's not just an academic exercise (PhD thesis even) or wishful thinking, akin to the Semantic Web or Strong AI?

http://www.ietf.org/rfc/rfc5023.txt

There's no need to be sarcastic.

I think you're being too hard on it. It's difficult for me to see how a general-purpose library could cover many of those things.

Could it go further, and do a better job of encouraging people to use REST? Sure. But it's trying to be pragmatic, and right now we're dealing with a world where people think that their unwillingness to learn is an argument against an architectural style.

:( Did anyone else expect this to be about EVE Online?

I too am disappointed about this.

EVE has really good community APIs & toys (such as the market place firehose, not sure if that's still around), I guess the developers who play it need something to do when they are mining ;-).

Under the hood, is this API event-based, thread-based, or both?

Under the hood, it's Flask, so it's WSGI. WSGI can be served in a variety of ways.

does it generate documentation for all link relations, media types, and available resources in workspace?

Hello, there's a third party tool called Eve-Docs http://blog.python-eve.org/eve-docs. It is a work in progress, and looks promising.

Disappointed that this is not the much-awaited REST API for EVE online (a game written in python)...

I totally thought this would be a third party CREST-like (CREST is what the EVE online REST API is called. The 'C' is for 'Carbon') hack of some sorts.

Reply on news.ycombinator.com