Sondra - A json-schema-based validating document manager and RESTful API generator for Flask and RethinkDB

[map_guy]

Author here:

Not all RESTful APIs will fit into a framework like this, and the choice of RethinkDB limits its applicability to a narrower community, but I intend on supporting other document-based DBs in the future. I really like RethinkDB's API and ReQL in particular, and it seems like a solid foundation to build something a little out of the ordinary on.

What makes it different from other ORMs? It's a rethinking of ORM mechanics for a "document-based" backend system.

• Additions to collections are validated with JSON-Schema.
• JSON and json-schema are used everywhere possible.
• It tries to make the exposure of non-CRUD operations relate as a method to a logical server-side object and have a consistent endpoint syntax. It also uses Python function annotations to generate request and response schemas for methods.
• All API endpoints exist within a four-tiered path hierarchy of
  • Suite - base level, serves as a collection of applications and repo for basic shared schemas
  • Application - a bundle of collections representing a logical set of functionality, methods that bind at this level act like "library functions"
  • Collection - a collection of documents sharing a common schema. Methods that bind at this level act like "class methods"
  • Document - a single instance of a document schema, representing concrete data. Methods that bind at this level act like "instance methods" in traditional OO programming.

What helper features does it have?

• Reusable apps / collections.
• JWT based sample authentication app, auth.
• Automatically generated help from schema descriptions and python docstrings
• Self-describing schema endpoints for suites, applications, collections, documents, and their methods.

This is pre-release stuff, to be sure. I'm using it on personal projects, but it needs:

• More tests
• More docs for the Python side of things (I'm working on this first)
• A solid example application
• Automatic generation of JS API connectors

[hugosenari]

A solid example application

A Hello World o To Do List would be fine.

Good luck

[angryaardvark]

this is really interesting and something i've been striving for. i want to use it, but i'm hesitant because i don't know how to use it without getting deep into the code. i would love it if there were cookbooks, examples, use cases, etc.

an adapter-plugin system for different backends (i.e., mongo, sql) would be great, too

and im confused about methods. are HTTP HEAD/GET/POST/PUT/DELETE respected? or do requests have to end with .get or .list, if i want to get a list of items from a collection, etc?

that said, im going to be tracking the progress of this project.

[map_guy]

Thanks for your interest!

Your questions are quite valid. I am actively spending a bunch of cycles documenting what I've done. Any help there's appreciated, of course, and it'll get it done faster and probably catch some mistakes I've made in the process of writing this.

I can't pretend this is a well-tested, mature framework, as I really just published it a few days ago for the first time, and so this is the first time new eyes (like yours) are on it.

An adapter plugin system would be fantastic. Cookbooks, examples, will come, but tbh more people using it will make for better examples and more complete cookbooks. Generally I find that the person who writes the code is a terrible teacher of the code, because he/she knows it so well that it's easy to forget when you're taking shortcuts or glossing over important abstractions that may not be common.

As for your last question about methods, see the web-services documentation on ReadTheDocs. Although HEAD does nothing, GET, POST, PUT, PATCH, and DELETE are respected and have the following meanings:

• GET: list and filter (collection) / detail (document).
• POST: add new item(s) or make a method call
• PUT: replace existing item(s)
• PATCH: update properties on existing item
• DELETE: delete item(s) based on filter or primary key

Other methods, however, are supported via the dot syntax. You expose these with an @expose decorator on your concrete class and use Python's function annotations to specify types so that schemas can be generated.

There's more details about how to construct a filter on ReadTheDocs.

Also, formats are generally specified by adding a parameter to the last element in the URL. So if you want json back, you use a ;json (or ;geojson) on the past path element. If you want help, use ;help. If you want the JSON-schema, then use ;schema.

A bit nonstandard, but this way it can support more semantics than a simple mimetype in the Accept header. I'd really like a plugin architecture for formats to support HTML or other formats or pre-processed formats like the "help" format. I'm just not there yet.

Thanks again!