Automatically-generated API console (HTML forms/views)

[budowski]

Used while developing - similar to what djagno-rest-framework has.

[dankrause]

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.

[budowski]

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?

[dankrause]

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.

[budowski]

Interesting idea - I think I'll implement it in a similar fashion... Thanks :-)

[dankrause]

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.

[budowski]

Also a good idea - but we'll need to let the user define the URL that will be used for querying that info

[budowski]

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.

[dankrause]

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.

[dankrause]

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.