Sample API Client

:copyright (c) 2014 - 2015, The Regents of the University of California, through Lawrence Berkeley National Laboratory (subject to receipt of any required approvals from the U.S. Department of Energy) and contributors. All rights reserved. # NOQA :author

class seed.utils.api_client.APIClient(base_url, api_key='', email_address='')

Implementation of a demonstration client for using SEED’s API.

Example Usage:

client = APIClient('http://seeddomain.com',
                   api_key='your_key_here',
                   email_address='youremail@address.com')

# get all orgs user belongs to
client.get_organizations()

# organization id 17 will now be used for most requests
client.set_organization(17)

# create a dataset
client.create_dataset('dataset name here')
>>> {u'id': 34, u'name': u'test_data_set2', u'status': u'success'}

# upload a file
client.upload_file('/path/to/file', 34, 'Assessed Raw')
>>> {'import_file_id': 54,
     'success': true,
     'filename': 'DataforSEED_dos15.csv'}

# save the file's to the DB as raw buildings
client.save_raw_data(payload={'file_id': 54})
>>> {u'progress_key': u':1:SEED:save_raw_data:PROG:54',
     u'status': u'success'}

# check the progress of the saving
client.progress(
    payload={'progress_key':':1:SEED:save_raw_data:PROG:54'}
)
>>> {u'progress': 78,
     u'progress_key': u':1:SEED:save_raw_data:PROG:54'}

For nearly all endpoints, functions named for the endpoint are created from the get_api_schema endpoint. If an endpoint requires a payload it can be provided as a dictionary to the keyword ‘payload’:

client.update_project(
    payload={'project':
        {'project_slug': 'myproject',
         'name': 'My Project',
         'description': 'My description here',
         'end_date': 1407231741,
         'deadline_date': 1407200000
         }
    }
>>> {'status': 'success'}

If an endpoint requires a GET query string, provide those parameters as a dict to the keyword ‘params’:

client.get_import_file(params={'import_file_id': 54})
>>> {'status': 'success',
     'import_file': {<snip>}
    }

create_dataset(name)

Example method including a payload.

Args:

name: The name of the new dataset.

Returns:

{‘id’: 34, ‘name’: name, ‘status’: ‘success’}

describe(what)

Provides a human-readable description of an endpoint, specified either by name or URI. E.g.:

client.describe('save_match')
>>> save_match
>>> /app/save_match/
>>> Adds or removes a match between two BuildingSnapshots[...]

get_organizations()

Example method for overriding the autogenerated methods.

Returns:

All organizations the user belongs to. See ``seed.views.accounts.get_organizations()’‘

get_schema()

Retrieves all of the API endpoints for this SEED instance.

set_organization_id(org_id)

Sets the client’s organization_id. As this is needed for most requests, you can set it once and include it in all requests.

Args:

org_id: An ID of an org the user belongs to. Will validate against

the API.

upload_file(filepath, import_record_id, source_type)

Determines the correct method to upload a file (S3 or direct) and does so. Makes use of several endpoints in the process, depending on where the SEED instance stores files.

Args:

filepath: Full path to file on local filesystem. import_record_id: ID of the dataset to associate file with. source_type: Usually one of ‘Assessed Raw’ or ‘Portfolio Raw’

Returns:

{“import_file_id”: 54,

“success”: true, “filename”: “DataforSEED_dos15.csv”}