API_GetSchema
Don't forget to check out our JSON RESTful APIs, they can help you utilize and extend Quickbase with ease.
Overview
Use API_GetSchema to get information about the specified application or application table.
When invoked on an application dbid, this call returns DBVars created for the application and all child table dbids.
When invoked on a table dbid, the call returns DBVars and additional table-related information such as reports, field IDs (fid), key field ID (key_fid), individual record names, base type, and the current property settings for each field. In addition, this call returns the default List All and List Changes reports.
This call also returns any custom reports that you have created in the UI and saved as a common report. You can then use the query ID or query name in the various API calls that use queries, instead of manually constructing the query string yourself. See API_SetFieldProperties and API_DoQuery for more information on field property values.
Here’s a sample of what one of these saved queries looks like in the response:
<query id="5">
<qname>Complete Refuel</qname>
<qytype>table</qytype>
<qydesc>fuel quantity greater than 10 gallons</qydesc>
<qycrit>({'7'.AF.'03-24-2008'}AND{'6'.EX.'10'})</qycrit>
<qyclst>8.6</qyclst>
<qyopts>nos.</qyopts>
<qycalst>0.0</qycalst>
</query>
This call can be used to create tooltips for your application based on the field help in your Quickbase application. You can use API_GetSchema to get the field help and then load it into tooltips.
API_GetSchema lists summary field metadata. For example, Total Actual Hours is a summary field defined in a project table representing the actual number of hours team members have logged against tasks on time cards. It is based on the following field definitions:
It uses a relationship based on a reference field “related project” (fid: 48), and the API returns it as summaryReferenceFid
The field that it is summarizing is Actual Hours (fid: 133), and the API returns it as summaryTargetFid
The summary function is Total, and the API returns it as is
The sample code displays as follows:
<field>
<summaryReferenceFid>48</summaryReferenceFid>
<summaryTargetFid>133</summaryTargetFid>
<summaryFunction>Total</summaryFunction>
</field>
Request parameters
| Parameter | Value | Required? |
|---|---|---|
ticket | A valid authentication ticket. The authentication ticket is returned via the API_Authenticate call. | yes, one of:
|
usertoken | The user token is an alternative means of authentication, used for API access. User tokens cannot be used to access the Quickbase UI. | yes, one of:
|
apptoken | A valid application token. | yes, if the application requires application tokens |
udata | A string value that you want returned. It will not be handled by Quickbase but it will be returned in the response. | no |
Response values
| Element Name | Value |
|---|---|
action | The originating request, for example, API_GetSchema. |
| date_format | The date configuration for the app or the table. Date formats supported are:
Note that each element of the date format is separated by a dash (-), and dates are saved in this format. |
errcode | Identifies the error code, if any. (See the Error Codes appendix for a list of possible error codes.) 0 indicates that no error was encountered. |
errtext | Text that explains the error code. "No error" indicates that no error was encountered. |
time_zone | A string value that defines the application's time zone. |
udata | Optional. Contains any udata value supplied in the request. |
table | Contains all of the application or table metadata, depending on the dbid supplied in the request. |
Sample XML Request
POST https://target_domain/db/target_dbid
HTTP/1.0
Content-Type: application/xml
Content-Length:
QUICKBASE-ACTION: API_GetSchema
<qdbapi>
<udata>mydata</udata>
<ticket>auth_ticket</ticket>
<apptoken>app_token</apptoken>
</qdbapi>
URL alternative
https://target_domain/db/target_dbid?a=API_GetSchema&ticket=auth_ticket
&apptoken=app_token&udata=mydata
where target_domain is the domain against which you are invoking this call, for example, quickbase.com. Read about this notation.
Sample Application-level Response
<?xml version="1.0" ?>
<qdbapi>
<action>API_GetSchema</action>
<errcode>0</errcode>
<errtext>No error</errtext>
<time_zone>(UTC-08:00) Pacific
Time (US & Canada)</time_zone>
<date_format>YYYY-MM-DD</date_format>
<udata>mydata</udata>
<table>
<name>API
created Sample</name>
<desc>This
is a sample application.</desc>
<original>
<app_id>bdb5rjd6h</app_id>
<table_id>bdb5rjd6h</table_id>
<cre_date>1204586581894</cre_date>
<mod_date>1206394201119</mod_date>
<next_record_id>1</next_record_id>
<next_field_id>7</next_field_id>
<next_query_id>5</next_query_id>
<def_sort_fid>6</def_sort_fid>
<def_sort_order>1</def_sort_order>
</original>
<variables>
<var
name="Blue">14</var>
<var
name="Jack">14</var>
<var
name="Magenta">12</var>
<var
name="usercode">14</var>
</variables>
<chdbids>
<chdbid
name="_dbid_doug_s_api_created_sample">bdb5rjd6g</chdbid>
<chdbid
name="_dbid_vehicle">bddrydqhg</chdbid>
</chdbids>
<fields></fields>
</table>
</qdbapi>
Sample Table-level Response
<?xml version="1.0" ?>
<qdbapi>
<action>API_GetSchema</action>
<errcode>0</errcode>
<errtext>No error</errtext>
<time_zone>(UTC-08:00) Pacific Time (US & Canada)</time_zone>
<date_format>YYYY-MM-DD</date_format>
<udata>mydata</udata>
<table>
<name>API created Sample</name>
<desc>This is a sample contact manager table.</desc>
<original>
<table_id>bdb5rjd6g</table_id>
<app_id>bdb5rjd6g</app_id>
<cre_date>1204586581894</cre_date>
<mod_date>1206394201119</mod_date>
<next_record_id>22</next_record_id>
<next_field_id>24</next_field_id>
<next_query_id>5</next_query_id>
<def_sort_fid>6</def_sort_fid>
<def_sort_order>1</def_sort_order>
</original>
<variables>
<var name="Blue">14</var>
<var name="Jack">14</var>
<var name="Magenta">12</var>
<var name="usercode">14</var>
</variables>
<queries>
<query id="1">
<qyname>List All</qyname>
<qytype>table</qytype>
<qycalst>0.0</qycalst>
</query>
<query id="2">
<qyname>List Changes</qyname>
<qytype>table</qytype>
<qydesc>Sorted by Date Modified</qydesc>
<qyslst>2</qyslst>
<qyopts>so-D.onlynew.</qyopts>
<qycalst>0.0</qycalst>
</query>
</queries>
<fields>
<field id="6" field_type="text"
base_type="text">
<label>Additional Information</label>
<fieldhelp>Supply additional data about
the problem.</fieldhelp>
<nowrap>0</nowrap>
.
.
.
</field>
</fields>
</table>
</qdbapi>
