Schema - Open Data API
The /schema
endpoint returns information about the SuperSTAR datasets that are available to you, and their fields and measures.
Overview
Endpoint | http://<server>/webapi/rest/v1/schema |
---|---|
HTTP Method | GET |
Request Headers
Accept-Language | The language that labels will be returned in (setting this is equivalent to changing the dataset and user interface language in SuperWEB2). | Optional. If not set, the server default language will be used. |
---|---|---|
APIKey | The API Key to use to authenticate this request. You can obtain your API key from the Preferences page in SuperWEB2. | Required in all requests. |
If-None-Match | If you provide a known Etag value, then (if the response has not changed) this endpoint will return a 304 response instead of the response body. 304 responses do not count against your rate limit usage. | Optional. If not set, the request will count against your rate limit usage. |
---|
Response Headers
X-RateLimit | The rate limit configured for this server. By default, this is set to 100. |
---|---|
X-RateLimit-Remaining | The number of requests remaining for the current rate limiting period. If this value drops to 0 then you will not be able to submit any further requests using this API key until the limit resets. |
X-RateLimit-Reset | The time when the rate limit will next be reset. This is expressed as a UNIX timestamp in milliseconds (the number of milliseconds since January 1st 1970). |
Etag | The checksum of the response. You can store this and use it in the If-None-Match header in subsequent requests. This will allow you to check whether the resource has changed without affecting your rate limit. |
---|
Link | If the response returns a large number of child values then it may be subject to pagination (by default, this occurs if there are over 100 child values, although your administrator may have configured a different limit). When the response is paginated, this header will contain a link to the next page of results. If this header is not returned then this indicates either that the response was not paginated, or that the current response contains the last page of results. |
---|
Response Body
The root endpoint, /schema
, returns details of all datasets and folders at the root level of the SuperSTAR server that your user account has permission to access. For example, the following response indicates that there are two datasets installed at the root level that you have permission to access: people and bank.
{
"id": "str:folder:root",
"label": "SuperSTAR Database Server",
"location": "http://localhost:8080/webapi/rest/v1/schema/str%3Afolder%3Aroot",
"type": "FOLDER",
"children": [
{
"id": "str:database:people",
"label": "People",
"location": "http://localhost:8080/webapi/rest/v1/schema/str%3Adatabase%3Apeople",
"type": "DATABASE"
},
{
"id": "str:database:bank",
"label": "Retail Banking",
"location": "http://localhost:8080/webapi/rest/v1/schema/str%3Adatabase%3Abank",
"type": "DATABASE"
}
]
}
As shown by this example, each object that is described in the response has a unique ID that begins with str:
. You can append this to the URL to obtain more details about that object. For example, querying /schema/str:database:bank
returns information about the Retail Banking database:
{
"id": "str:database:bank",
"label": "Retail Banking",
"location": "http://localhost:8080/webapi/rest/v1/schema/str%3Adatabase%3Abank",
"type": "DATABASE",
"children": [
{
"id": "str:count:bank:F_Customer",
"label": "Customers",
"location": "http://localhost:8080/webapi/rest/v1/schema/str%3Acount%3Abank%3AF_Customer",
"type": "COUNT"
},
{
"id": "str:measure:bank:F_Customer:Cust_Profit",
"label": "Customer Profit",
"location": "http://localhost:8080/webapi/rest/v1/schema/str%3Ameasure%3Abank%3AF_Customer%3ACust_Profit",
"type": "MEASURE"
},
{
"id": "str:count:bank:F_Account",
"label": "Accounts",
"location": "http://localhost:8080/webapi/rest/v1/schema/str%3Acount%3Abank%3AF_Account",
"type": "COUNT"
},
{
"id": "str:measure:bank:F_Account:Acc_Profit",
"label": "Account Profit",
"location": "http://localhost:8080/webapi/rest/v1/schema/str%3Ameasure%3Abank%3AF_Account%3AAcc_Profit",
"type": "MEASURE"
},
{
"id": "str:measure:bank:F_Account:Avg_Acc_Balance",
"label": "Average Account Balance",
"location": "http://localhost:8080/webapi/rest/v1/schema/str%3Ameasure%3Abank%3AF_Account%3AAvg_Acc_Balance",
"type": "MEASURE"
},
{
"id": "str:folder:bank:Customers",
"label": "Customers",
"location": "http://localhost:8080/webapi/rest/v1/schema/str%3Afolder%3Abank%3ACustomers",
"type": "FOLDER"
},
{
"id": "str:folder:bank:Accounts",
"label": "Accounts",
"location": "http://localhost:8080/webapi/rest/v1/schema/str%3Afolder%3Abank%3AAccounts",
"type": "FOLDER"
}
]
}
You can use any of the IDs returned here to further explore the schema, for example you might call /schema/str:folder:bank:Customers
to query the fields available in the Customers folder within the Retail Banking dataset.
Schema Types and Associated ID Schemes
The following is a list of all the available schema types and their corresponding ID schemes:
Type | ID Scheme | Example |
---|---|---|
Count | str:count:<dataset_id>:<fact_table> | str:count:bank:F_Customer |
Dataset | str:database:<dataset_id> | str:database:bank |
Field | str:field:<dataset_id>:<fact_table>:<field> | str:field:bank:F_Customer:Gender |
Folder (SuperADMIN) | str:folder:<folder_id> | str:folder:sharedtables |
Folder (grouping within a dataset) | str:folder:<dataset_id>:<folder_id> | str:folder:bank:Customers |
Measure | str:measure:<dataset_id>:<fact_table>:<measure> | str:measure:bank:F_Customer:Cust_Profit |
Statistical Function | str:statfn:<dataset_id>:<fact_table>:<measure>:<function> | str:statfn:bank:F_Customer:Cust_Profit:SUM |
Value | str:value:<dataset_id>:<fact_table>:<field>:<valueset>:<value> | str:value:bank:F_Customer:Gender:C_Gender:M |
Valueset | str:valueset:<dataset_id>:<fact_table>:<field>:<valueset> | str:valueset:bank:F_Customer:Gender:C_Gender |