all-models.py

# option 1: all models
project = unify.projects.getByName('Customers Q4 2018') # returns Project model
ud1 = project.unified_dataset # returns Dataset model.
# Note: could have unified_dataset be a dynamic property or a method... (`.unified_dataset` vs `.unified_dataset()`)

ud2 = unify.projects.getByName('Suppliers Q3 2017').unified_dataset

api-query-builder.py

q = unify.projects.id('1') # returns an ApiQueryBuilder (as does unify.projects)
q = q.unified_dataset # we can get the builder at each step
q = q # OR we can chain calls
  .unified_attributes
  .some_method_of_unified_attributes
  
# now we need some way to send q...
# each of the following returns a model object (as opposed to a modified builder)
# option 1: single `send` method
q.send('POST')
# option 2: 1 method for each REST verb
q.post()
# option 3: semantically meaningful method (thing like `:verb` in the API)
q.run()

models-by-default.py

# I want to get the Unified Dataset for project with id = 'Customers Q4 2018'

# Easy usage: use Models to get other Models
project = unify.projects.get_by_name('Customers Q4 2018') # returns Project model
ud1 = project.unified_dataset # returns Dataset model.
# 2 requests were sent:
# 1. to instantiate the project as a Project model (not strictly necessary)
# 2. to instantiate the unified dataset as a Dataset model

# Advanced usage: prepare 1 query then get 1 Model back
unify.prepare_query() # prepareQuery returns a QueryBuilder
  .projects.get_by_name('Customers Q4 2018') # QueryBuilder method chaining: each methods returns another QueryBuilder with more parameters bound to it
  .unified_dataset
  .send() # terminal method (terminal method options still apply: e.g. .send vs .post vs .run)

the all-models approach is simple and I like the syntax for using it a lot. One drawback is that the user may send multiple requests when only 1 was necessary.

The api-query-builder approach allows users to distinguish between composing the query (without sending any requests and getting back any model objects) and sending the query. This approach can leverage aliases in the RESTful HTTP API to send the minimum number of requests. I'm not sure how bad "multiple requests instead of using alias" would be...

I think I like api-query-builder, with semantic methods. Although I think we should use get(), put(val), and delete() for those sorts of requests.