Schema Endpoint

The /schema endpoint returns information about the SuperSTAR datasets that are available to you, their fields and measures, as well as any saved tables.

Overview

Endpoint	https://<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 Account 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

X-RateLimit-Schema

X-RateLimit-Table

The global, schema, and table rate limits (if configured).

The individual headers are only returned if the corresponding rate limit has been set. If none of these headers are returned then that indicates that no rate limiting applies.

X-RateLimit-Remaining

X-RateLimit-Remaining-Schema

X-RateLimit-Remaining-Table

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.

The individual headers are only returned if the corresponding rate limit has been set. If none of these headers are returned then that indicates that no rate limiting applies.

X-RateLimit-Reset

X-RateLimit-Reset-Schema

X-RateLimit-Reset-Table

The time when the rate limit will next be reset. This is expressed as a UNIX timestamp in milliseconds (milliseconds since January 1st 1970).

The individual headers are only returned if the corresponding rate limit has been set. If none of these headers are returned then that indicates that no rate limiting applies.

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.

CODE

{
  "id": "str:folder:root",
  "label": "SuperSTAR Database Server",
  "location": "http://localhost:8080/webapi/rest/v1/schema/str:folder:root",
  "type": "FOLDER",
  "children": [
    {
      "id": "str:database:people",
      "label": "People",
      "location": "http://localhost:8080/webapi/rest/v1/schema/str:database:people",
      "type": "DATABASE"
    },
    {
      "id": "str:database:bank",
      "label": "Retail Banking",
      "location": "http://localhost:8080/webapi/rest/v1/schema/str:database:bank",
      "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:

CODE

{
  "id": "str:database:bank",
  "label": "Retail Banking",
  "location": "http://localhost:8080/webapi/rest/v1/schema/str:database:bank",
  "type": "DATABASE",
  "lastModified": 1537770425416,
  "recordViewEnabled": true,
  "children": [
    {
      "id": "str:count:bank:F_Customer",
      "label": "Customers",
      "location": "http://localhost:8080/webapi/rest/v1/schema/str:count:bank:F_Customer",
      "type": "COUNT",
            "functions": [
                "COUNT"
            ]
    },
    {
      "id": "str:measure:bank:F_Customer:Cust_Profit",
      "label": "Customer Profit",
      "location": "http://localhost:8080/webapi/rest/v1/schema/str:measure:bank:F_Customer:Cust_Profit",
      "type": "MEASURE",
            "functions": [
                "SUM",
                "MEDIAN",
                "MEAN"
            ]
    },
    {
      "id": "str:count:bank:F_Account",
      "label": "Accounts",
      "location": "http://localhost:8080/webapi/rest/v1/schema/str:count:bank:F_Account",
      "type": "COUNT",
            "functions": [
                "COUNT"
            ]
    },
    {
      "id": "str:measure:bank:F_Account:Acc_Profit",
      "label": "Account Profit",
      "location": "http://localhost:8080/webapi/rest/v1/schema/str:measure:bank:F_Account:Acc_Profit",
      "type": "MEASURE",
            "functions": [
                "SUM",
                "MEDIAN",
                "MEAN"
            ]
    },
    {
      "id": "str:measure:bank:F_Account:Avg_Acc_Balance",
      "label": "Average Account Balance",
      "location": "http://localhost:8080/webapi/rest/v1/schema/str:measure:bank:F_Account:Avg_Acc_Balance",
      "type": "MEASURE",
            "functions": [
                "SUM",
                "MEDIAN",
                "MEAN"
            ]
    },
    {
      "id": "str:group:bank:X_Customers",
      "label": "Customers",
      "location": "http://localhost:8080/webapi/rest/v1/schema/str:group:bank:X_Customers",
      "type": "GROUP"
    },
    {
      "id": "str:group:bank:X_Accounts",
      "label": "Accounts",
      "location": "http://localhost:8080/webapi/rest/v1/schema/str:group:bank:X_Accounts",
      "type": "GROUP"
    }
  ]
}

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.

Retrieve Entire Schema or Dataset

By default:

A request to the /schema endpoint only returns items at the root level. For example, it will return details of any folders but not the contents of those folders. To retrieve the entire schema, you need to submit multiple requests to traverse the hierarchy.
A request for a specific dataset only returns items at the root level of that dataset. For example, it will return details of folders at the root level of the dataset, but not any fields, valuesets or values within those folders.

You can supply additional parameters in the request that instruct the API to retrieve the entire schema in a single request:

Catalogue	?depth=folder	Recurse into all folders (returns all datasets and tables)	https://<server>/webapi/rest/v1/schema?depth=folder
Datasets	?depth=folder	Recurse into all folders (returns all fields)	https://<server>/webapi/rest/v1/schema/str:database:bank?depth=folder
	?depth=field	Recurse into all fields (returns all valuesets)	https://<server>/webapi/rest/v1/schema/str:database:bank?depth=field
	?depth=valueset	Recurse into all valuesets (returns all values)	https://<server>/webapi/rest/v1/schema/str:database:bank?depth=valueset

If you specify an invalid depth value, the API will return a 422 response with an error message.

Saved Tables

The /schema endpoint also returns details of saved tables that are accessible to you (tables saved in the User Data Repository that your account has permission to access).

For example:

CODE

    {
      "id": "str:table:1c9bbc74-ee60-4783-817d-899470c1c965",
      "label": "My Saved Table",
      "location": "http://localhost:8080/webapi/rest/v1/schema/str:table:1c9bbc74-ee60-4783-817d-899470c1c965
      "type": "TABLE"
    }

In this example 1aedc52f-52fc-4eeb-b18e-88b17868b481 is the table ID. IDs are automatically assigned to tables when they are saved to the User Data Repository.

You can use the full returned ID value with the /table/saved endpoint to submit a query for this table. Learn More.

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:group:<dataset_id>:<prefix>_<folder_id>	str:group:bank:X_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
Table	str:table:<table_id>	str:table:af6c0116-42f6-4513-bb2b-95c05a4b3894
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

Group Prefixes

The prefix in a group folder ID indicates what type of group it represents:

G_	A general group.
X_	A group of classification fields.
M_	A group of measures/summations.
D_	A group of plain fields.

The general and plain group types are not typically used. The most common group types you will encounter are classifications and measures.

The prefix was added to the ID format in version 9.9.2 to allow the API to distinguish between different types of group with the same name. Prior to 9.9.2 the ID of a group used the following format: str:folder:<dataset_id>:<folder_id>

Measures

SXV4 datasets can have two types of summation option: record counts and numeric measures.

As shown in the above examples, when you query for the schema of a dataset, the API returns the available fields, groups and summation options at the top level. At this level, counts and numeric measures have IDs with the following formats:

count	str:count:<dataset_id>:<fact_table>	str:count:bank:F_Customer
measure	str:measure:<dataset_id>:<fact_table>:<measure>	str:measure:bank:F_Customer:Cust_Profit

When you want to construct a query to pass in to the /table endpoint, you can use the count IDs in this format, but for measures, the ID you need to use in the query should be in the format str:statfn:<dataset_id>:<fact_table>:<measure>:<function>. This allows you to specify the statistical function you want to use.

You can get the available functions by passing the str:measure:<dataset_id>:<fact_table>:<measure> ID back to the /schema endpoint. This will give you all the available statistical functions for that particular measure.

For example, querying /schema/str:measure:bank:F_Customer:Cust_Profit will return something similar to the following:

CODE

{
    "id": "str:measure:bank:F_Customer:Cust_Profit",
    "label": "Customer Profit",
    "location": "http://localhost:8080/webapi/rest/v1/schema/str:measure:bank:F_Customer:Cust_Profit",
    "type": "MEASURE",
    "functions": [
        "SUM",
        "MEDIAN",
        "MEAN"
    ],
    "children": [
        {
            "id": "str:statfn:bank:F_Customer:Cust_Profit:SUM",
            "label": "Customer Profit",
            "location": "http://localhost:8080/webapi/rest/v1/schema/str:statfn:bank:F_Customer:Cust_Profit:SUM",
            "type": "STAT_FUNCTION"
        },
        {
            "id": "str:statfn:bank:F_Customer:Cust_Profit:MEDIAN",
            "label": "Median of Customer Profit",
            "location": "http://localhost:8080/webapi/rest/v1/schema/str:statfn:bank:F_Customer:Cust_Profit:MEDIAN",
            "type": "STAT_FUNCTION"
        },
        {
            "id": "str:statfn:bank:F_Customer:Cust_Profit:MEAN",
            "label": "Mean of Customer Profit",
            "location": "http://localhost:8080/webapi/rest/v1/schema/str:statfn:bank:F_Customer:Cust_Profit:MEAN",
            "type": "STAT_FUNCTION"
        }
    ]
}

In this example, we can use either str:statfn:bank:F_Customer:Cust_Profit:SUM, str:statfn:bank:F_Customer:Cust_Profit:MEDIAN or str:statfn:bank:F_Customer:Cust_Profit:MEAN in a table query.

Weighted Datasets

The Open Data API supports weighted datasets. When you query the schema of a weighted dataset, the results will include details of the weighted measures. For example:

CODE

{
    "id": "str:database:ACS_2014_5Y_MW",
    "label": "ACS 2014 5Y Weighted",
    "location": "http://localhost:8080/webapi/rest/v1/schema/str:database:ACS_2014_5Y_MW",
    "type": "DATABASE",
    "lastModified": 1537768282404,
    "recordViewEnabled": true,
    "children": [
        {
            "id": "str:count:ACS_2014_5Y_MW:F_Housing_2014_5YR",
            "label": "Housing",
            "location": "http://localhost:8080/webapi/rest/v1/schema/str:count:ACS_2014_5Y_MW:F_Housing_2014_5YR",
            "type": "COUNT",
            "functions": [
                "COUNT"
            ],
            "weights": [
                {
                    "id": "str:measure:ACS_2014_5Y_MW:F_Housing_2014_5YR:WGTP",
                    "label": "Weighted Sum of Housing",
                    "location": "http://localhost:8080/webapi/rest/v1/schema/str:measure:ACS_2014_5Y_MW:F_Housing_2014_5YR:WGTP",
                    "type": "MEASURE"
                }
            ]
        },
        {
            "id": "str:measure:ACS_2014_5Y_MW:F_Housing_2014_5YR:WGTP",
            "label": "Weighted Sum of Housing",
            "location": "http://localhost:8080/webapi/rest/v1/schema/str:measure:ACS_2014_5Y_MW:F_Housing_2014_5YR:WGTP",
            "type": "MEASURE",
            "functions": [
                "SUM"
            ]
        }
    ]
}