Clients¶
There are two primary “clients”.
There is the high-level QuickbaseTableClient
which wraps the lower-level
QuickbaseApiClient
.
QuickbaseTableClient¶
-
class
quickbase_client.
QuickbaseTableClient
(table: Type[quickbase_client.orm.table.QuickbaseTable], user_token, agent='python', normalize_unicode=True, allow_deletes=False)¶ Class for making API calls relative to a specific QuickBase table.
This includes making calls for the app in general.
All calls (except
query()
) return aResponse
object for the HTTP response.Note
Pagination is not handled in any of these methods (yet).
- Variables
table – The underlying
QuickbaseTable
api – The wrapped
QuickbaseApiClient
- Parameters
user_token – The user token to authenticate.
agent – The agent header to send in requests.
normalize_unicode – Whether the JSON Serializer should normalize accented characters so that they can be encoded in Quickbase.
allow_deletes (bool) – Whether the client should be allowed to perform delete requests. Defaulted to False for now. But note that this is subject to change in 1.0 if there is a different general preference.
-
__init__
(table: Type[quickbase_client.orm.table.QuickbaseTable], user_token, agent='python', normalize_unicode=True, allow_deletes=False)¶ Initialize self. See help(type(self)) for accurate signature.
-
add_record
(rec, *args, **kwargs)¶ Aliased to
add_records()
making rec a list.
-
add_records
(recs: List[Union[quickbase_client.orm.table.QuickbaseTable, Any]], merge_field_id=None, fields_to_return=None)¶ Add record.
https://developer.quickbase.com/operation/upsert
- Parameters
recs – A list of items that are either the raw record data to post, or the
QuickbaseTable
object/record.merge_field_id – The list of fields to merge on.
fields_to_return – The list of field ID’s to return (default None which means all).
-
change_record_owner
(rid, new_owner)¶ Use the legacy API to change a Record’s owner.
See https://help.quickbase.com/api-guide/change_record_owner.html
- Parameters
rid – The record ID to change the owner of
new_owner – The email address, or user ID, of the user to change to the owner.
-
get_app
()¶ Get an app.
-
get_field
(field: Union[quickbase_client.orm.field.QuickbaseField, int])¶ Get fields for a table.
https://developer.quickbase.com/operation/getField
- Parameters
field – either the field ID or a
QuickbaseField
-
get_fields_for_table
()¶ Get fields for a table.
-
get_report
(report)¶ Get report.
https://developer.quickbase.com/operation/getRepor
- Parameters
report – Either the report name to lookup, the report id, or a
QuickbaseReport
object.
-
get_reports_for_table
()¶ Get reports for a table.
-
get_table
()¶ Get a table.
-
get_tables_for_app
()¶ Get an tables for an app.
-
query
(query_obj: Optional[quickbase_client.query.query_base.QuickbaseQuery] = None, raw=False, pager: Optional[quickbase_client.client.pager.ResponsePager] = None)¶ Do a query.
https://developer.quickbase.com/operation/runQuery.
See
query
for more.See
ResponsePager
for handling pagination.If some fields are coming back as null, a common “gotcha” is that the Quickbase API by default only returns fields listed as “default” in a table. In that case you would have to explicitly specify a
select
in the query, or you can edit the fields in Quickbase to be default fields.- Parameters
query_obj – The
QuickbaseQuery
object to use. Note that this object also specifies theselect
,group_by
,sort_by
, etc. So to specify those you need to specify them in the providedQuickbaseQuery
. See its documentation for more details.raw – If true, returns a requests.Response, else the data is serialized to a table object.
pager – A
ResponsePager
to handle making paginated requests.
-
run_report
(report, skip=None, top=None)¶ Run report.
https://developer.quickbase.com/operation/runReport.
- Parameters
report – Either the report name to lookup, the report id, or a
QuickbaseReport
object.skip (int) – For paging (see Quickbase API)
top (int) – For paging (see Quickbase API)
QuickbaseApiClient¶
-
class
quickbase_client.
QuickbaseApiClient
(user_token, realm_hostname, agent='python', allow_deletes=False)¶ The lower-level client to make API requests.
Note
Current alias of
QuickBaseApiClient
for backwards compatibility - will be removed in version 1.0Use
request()
to make an arbitrary request that forwards tomake_request()
- Variables
legacy_api – The
QuickbaseLegacyApiClient
for making requests to the XML API.
-
add_records
(table_id, data=None, merge_field_id=None, fields_to_return=None)¶
-
get_app
(app_id)¶
-
get_field
(field_id, table_id)¶
-
get_fields_for_table
(table_id)¶
-
get_report
(report_id, table_id)¶
-
get_reports_for_table
(table_id)¶
-
get_table
(app_id, table_id)¶
-
get_tables_for_app
(app_id)¶
-
query
(table_id, fields_to_select=None, where_str=None, sort_by=None, group_by=None, options=None)¶
-
request
(*args, **kwargs)¶
-
run_report
(report_id, table_id, skip=None, top=None)¶
QuickbaseLegacyApiClient¶
-
class
quickbase_client.
QuickbaseLegacyApiClient
(user_token: str, realm_hostname: str)¶ Legacy Client which makes requests to the old XML API.
This operates more generically to send any request to the old API. It’s primary purpose is to supplement the JSON API for things not yet supported.
It does include some higher-level methods for things that in particular are not supported in the new API’s. If there are others you would like added, submit an Issue or a Merge-Request and we can certainly add it!
Rather than get in to having lxml as an optional dependency, it will just deal with XML data as strings for now. If we want more support of the XML API, then it might be worth it to introduce that.
- Parameters
user_token (str) – The user token for authenticating with the API. Note that the other forms of authentication through the XML API are not supported via this library.
realm_hostname (str) – The hostname - like
"foo.quickbase.com"
-
change_record_owner
(table_id, rid, new_owner)¶ The Quickbase API_ChangeRecordOwner action
See https://help.quickbase.com/api-guide/change_record_owner.html
- Parameters
table_id – The table ID containing the record
rid – The record ID to change the owner of
new_owner – The email address, or user ID, of the user to change to the owner.
-
make_request
(http_method: str, quickbase_action: str, endpoint: str, request_data_xml_str='')¶ Used as a simple Python interface to the old XML API.
- Parameters
http_method (str) – The HTTP method, like
"post"
quickbase_action (str) – The Quickbase Action to send, like
"API_ChangeRecordOwner"
endpoint (str) – The HTTP Endpoint to call, like
/db/abc123
request_data_xml_str (str) – The data to add to the XML string that gets sent, inside of the
qdbapi
element/tag. For now this is all done through strings, in the future it may use lxml and have better capabilities for working with those trees.
RequestFactory¶
-
class
quickbase_client.client.request_factory.
QuickbaseRequestFactory
(user_token, realm_hostname, agent='python', encoder=None, allow_deletes=False)¶ -
make_request
(method, endpoint, additional_headers=None, params=None, data=None) → requests.models.Response¶ Make a request (synchronously) and return the Response.
- Parameters
method (string) – The (string) HTTP method.
endpoint (string) – The endpoint of the API (starting after “v1/” for example).
additional_headers (dict) – A dict of extra headers.
params – Query parameters.
data – The data to send in the body.
-
ResponsePager¶
-
class
quickbase_client.
ResponsePager
¶ Object to pass to methods (query) to manage pagination.
When calling something like QuickbaseTableClient.query, you can pass a ResponsePager, and repeatedly make requests while
more_remaining()
is True.pager = ResponsePager() while pager.more_remaining(): recs = my_client.query(pager=pager)
-
more_remaining
() → bool¶ Returns true if there is another request to be made.
-