Dataset API about mapbox-cli-py

[emilymcafee]

Related: https://github.com/mapbox/mapbox-data-cli

[perrygeo]

@emilymcafee - that looks great, we'll probably follow the design of mapbox-data-cli pretty closely for this tool.

[sgillies]

@perrygeo as per discussion yesterday, I think mapbox datasets action-resource will be a fine pattern.

There's a bug in our Datasets API documention. It says

Using the dataset API involves interacting with two types of resources: a dataset, which is a collection of features.

But there are actually four types of resources in /datasets/v1/{account}/{dataset}/features/{feature}:

1. The datasets container /datasets/v1/{account}.
2. The dataset /datasets/v1/{account}/{dataset}.
3. The dataset's feature container /datasets/v1/{account}/{dataset}/features.
4. The feature /datasets/v1/{account}/{dataset}/features/{feature}.

GETs on these 4 different URLs give 4 different responses. 4 different kinds of resources.

So, I propose we change your sketch above to

mapbox datasets list
mapbox datasets create [args]

mapbox datasets read-dataset DSNAME [args]
mapbox datasets update-dataset DSNAME [args]
mapbox datasets delete-dataset DSNAME [args]

mapbox datasets list-features DSNAME [args]
mapbox datasets batch-update-features DSNAME [args]

mapbox datasets read-feature DSNAME FNAME [args]
mapbox datasets update-feature DSNAME FNAME [args]
mapbox datasets delete-feature DSNAME FNAME [args]

Worth combining the DSNAME and FNAME into one argument? Something like DSNAME:FNAME?

[perrygeo]

👏 that's clarifies things immensely! Thanks @sgillies - maybe once we're done here we can suggest some api documentation changes.

I like separate args for easier composibility.

In terms of DSNAME and FNAME, are you refering to the id or actual names (feature name not being standard unless we require a properties.name which is icky)

[sgillies]

I'm using name and id interchangeably. Separate args works for me.

[rclark]

there are actually four types of resources

Hmm. I didn't consider the list of datasets as a distinct resource, but I see your point. If you think its confusing I'm happy to update the docs.

I can jump on this doc + CLI task as soon as @sgillies' work on the sdk wraps up.

[rclark]

I've started putting this together, and I'm getting to the batch_update_features function, which is always the problematic one.

From the CLI perspective, the goal in mapbox-data-cli was basically to expose three subcommands:

• mapbox dataset put-features: insert or update a set of features, performing as many backend requests as needed to get through the feature set
• mapbox dataset delete-features: delete a set of features, performing as many backend requests as needed to get through the id set
• mapbox dataset replace-dataset: list the ids in the dataset, delete them all and/or replace them with the features provided

Hidden here is a more generic question about how we want to handle "higher-level" commands that might result in multiple API requests.

[sgillies]

Closed via #32.