budowski
Automatically-generated API console (HTML forms/views)
Suggestion: Implement this by allowing the API client to request a description of each model. This will allow the client to automatically build an API console. You could simply include an HTML/JavaScript app in rest_gae that implements this entirely client-side.
Sounds like a good idea - but when you say "request a description of each model" - how would that be implemented? A new kind of endpoint? What's the "correct" way for RESTful APIs?
I'm not sure there is a specific "correct" RESTful way to do this. I've seen it done by adding a new resource type that you can query. For example, you could GET /api/models to return something like {u'next_results_url': None, u'results': [{u'class': u'Foo', u'properties': [ ... ] }, ...]}. It would have to be flexible enough to describe any subclass of ndb.Property, but that might be as easy as just supplying a class name and requiring the client to know what to do with them.
Interesting idea - I think I'll implement it in a similar fashion... Thanks :-)
Another suggestion - just doing GET /api could return the list, since you're technically returning a description of the whole API. That would also prevent you from colliding with a name that a user might want for one of their models.
Also a good idea - but we'll need to let the user define the URL that will be used for querying that info
Another way of exposing the models: When the client does an OPTIONS HTTP request to the endpoint (e.g. "OPTIONS /api/mymodel"), we'll return a JSON describing the model's properties.
I hadn't considered using OPTIONS. For reference, here's some arguments both for and against it: http://zacstewart.com/2012/04/14/http-options-method.html http://www.mnot.net/blog/2012/10/29/NO_OPTIONS
I'm convinced that it's a pretty good idea.
Here's another unrelated suggestion: If the model has a docstring, include it in the OPTIONS description. That would help allow the automatic generation of API docs.
Also, for the description format itself, this is worth a look: http://json-schema.org/examples.html
The example alone tells me that it will probably suit our needs. I haven't dug too deeply into the standard, so it might turn out to be a bit of a bloated monster like XML schema.