Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Redesign JSON output, ditch jsono, offer variants controlled by parameter instead #122

Closed
simonw opened this issue Nov 18, 2017 · 5 comments
Labels

Comments

@simonw
Copy link
Owner

simonw commented Nov 18, 2017

I want to support three variants for the rows output:

  • a list of lists, with a columns key saying what they are
  • a list of dictionaries
  • a single dictionary where the keys are the primary keys of the rows and the values are the row dictionaries themselves

I also want to make the various bits of metadata opt-in - so you don't get the SQL statement unless you ask for it.

These output options should be controlled by query string arguments.

I will set the .jsono URL to redirect to .json with the corresponding options.

@simonw simonw added this to the SQLite extensions edition milestone Nov 19, 2017
@simonw
Copy link
Owner Author

simonw commented Nov 19, 2017

For the overall shape of the rows:

?_shape=lists (default), ?_shape=objects, ?_shape=object (primary key as object keys)

For getting back extra keys:

?_extras=schema,query,timing

For expanding columns:

?_expand_all=1

Or ?_expand=qSpecies&_expand=qCaretaker

The template view will only be allowed to work with data it can request using extra options.

That leaves one sighted nasty edge-case: the default view will expand all columns, but the .json view of it won't?

I think that's OK. The default view won't include the extras used by the template to render the page either.

@simonw
Copy link
Owner Author

simonw commented Nov 19, 2017

This calls for refactoring the code so the table view, the row view and the custom SQL view share as much logic as possible.

@simonw
Copy link
Owner Author

simonw commented Nov 19, 2017

To start with, I could just ditch the .jsono in favour of the new _shape argument.

@simonw
Copy link
Owner Author

simonw commented Dec 5, 2017

I think .json should continue to return rows as list-of-lists - it's a nice default because it produces a smaller overall JSON file. Encouraging people to specify an alternative shape to get the current .jsono format feels appropriate.

simonw added a commit that referenced this issue Apr 3, 2018
simonw added a commit that referenced this issue Apr 3, 2018
Now instead of this:

	/database/table.jsono

We use the _shape parameter like this:

	/database/table.json?_shape=objects

Also introduced a new _shape called 'object' which looks like this:

	/database/table.json?_shape=object

Returning an object for the rows key:

	...
	"rows": {
		"pk1": {
			...
		},
		"pk2": {
			...
		}
	}

Refs #122
simonw added a commit that referenced this issue Apr 3, 2018
New _shape= parameter replacing old .jsono extension

Now instead of this:

	/database/table.jsono

We use the _shape parameter like this:

	/database/table.json?_shape=objects

Also introduced a new _shape called 'object' which looks like this:

	/database/table.json?_shape=object

Returning an object for the rows key:

	...
	"rows": {
		"pk1": {
			...
		},
		"pk2": {
			...
		}
	}

Refs #122
@simonw
Copy link
Owner Author

simonw commented Apr 3, 2018

The new documentation for the _shape= parameter is now live at http://datasette.readthedocs.io/en/latest/json_api.html

@simonw simonw closed this as completed Apr 8, 2018
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

No branches or pull requests

1 participant