Dataset API

[perrygeo]

The SDK PR is in the works. Meanwhile let's talk about the implications for the CLI...

As noted in the SDK planning ticket the Datasets API is a bit trickier as it involves two resources types: Datasets which are collections of Features. Then there are all of the standard "CRUD" operations on those resources.

How do we best represent these actions in the CLI? My initial thought is sub-sub-commands like:

mapbox dataset list-features
               read-features
               update-features
               delete-features
               list-datasets
               create-datasets
               read-datasets          

[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.