Getting Started
In this quick start guide, you'll learn how to:
- fetch a list of table objects with their guids
- read a table's metadata
- write a description to that table's metadata
In order to start using the API, you'll have to already have signed up your organization and performed metadata/catalog ingestion.
For reference, base url for all api calls is
https://api.production.selectstar.com/v1/
.Note that all of the API urls have a trailing backslash. If requests are missing the backslash our Rest API won't work as expected.
This guide will walk you through two different examples:
- 1.Using Postman, which is more interactive or user friendly, if you are not so familiar with coding just yet.
- 2.Using
curl
on the command line, which is tailored at more advanced users who are already familiar with scripting languages.
While this guide will use CURL, we recommend you get set up with a graphical user interface that will help you get to know the API in a more illustrative way. You can then move on to CURL, or chose your preferred scripting language.
To get set up with Postman, you first need to import our Postman Collection.
- 1.
- 2.Download our Select Star API Postman Collection. This collection contains all available endpoints in our API Reference Documentation. And will help you test them out effortlessly
- 3.Import the collection into postman
- 1.Use the shortcut ⌘+O or click the Import button at the top left.
- 2.Choose file downloaded Select Star API Postman Collection.json
- 3.Click import
Your postman collection is now ready to test and generate code snippets.
- 1.Go to the API Token page to find out how to generate an API token and copy it. You will need this token every time you make a call to the API regardless of the application or script you are using.
- 2.In Postman, configure the Authentication at the root level folder for Select Star API
- 1.Click on the root folder Select Star API.
- 2.Go to the Authorization tab
- 3.Choose API Key in the Type dropdown
- 4.Insert "Authorization" for the Key input.
- 5.Insert "Token {{apiKey}}". Here, {{apiKey}} can be the raw token you copied earlier, or you can chose to use Postman Environment Variables.Set up authorization
Your Authorization configuration is now complete. All folders nested under Select Star API will now inherit the authorization. You can now use the api to edit requests, send them and check responses.
- Postman also has a Documentation menu that will show you the documentation within their UI.
- Postman offers a code export version that will help you craft your scripts once you have configured the API call you need.
Once you have your token, you'll need to include it in any calls you make to the API. Set the Authorization header for bearer authentication like so:
Authorization: Token <token>
In curl you can set the header using the
-H
flag:curl https://api.production.selectstar.com/v1/tables/ -H "Authorization: Token <your_token>"
With authorization set, you can proceed to making a call to the API endpoint.
This section covers a more advanced example using CURL on the command line. It walks you through 2 specific examples: Reading a list of tables, and Writing descriptions to a table.
Feel free to use the tips above to use Postman in combination with this guide – or dive into it with plain code. Happy coding!
The end goal of this section is to be able to write a new description to a table. But in order to update a table, Select Star needs to know the table's guid; how can this be identified?
The endpoint you'll need to query is:
GET /tables/
There's many query parameters which allow filtering the result, such as
search_name
or serach_description
. For this example, let's search for names which include the substring sales
.curl -H "Authorization: Token <your_token>" "https://api.production.selectstar.com/v1/tables/?search_name=sales"
(Note that curl issues a
GET
request by default, even though you don't see it in the command)The response body will looks something like: (
...
indicates details on the object omitted here){
"count": 1,
"schema_count": 1,
"next": "http://url-to-next-page.selectstar.com",
"previous": "http://url-to-previous-page.selectstar.com",
"results": [
{
"guid": "ta_UUyFgbgRhVqhhHa5WCjBaa",
"database": {...},
"schema": {...},
"name": "sales",
"search_name": "dwh.analytics.sales",
"description": "global sales",
"created_by": {...},
"dsuser_created_by": {...},
"business_owner": {...},
"technical_owner": {...},
"updated_on": "2021-08-23T23:35:51Z",
"last_updated_on": "2021-08-23T23:35:51Z",
"last_queried_on": "2021-08-23T23:35:51Z",
"db_created_on": "2021-08-23T23:35:51Z",
"columns": [...],
"popularity": {...},
"tags": [...],
"updated_on": "2021-08-23T23:35:51Z",
"created_on": "2021-08-23T23:35:51Z",
"table_type": "table",
"data_type": "table",
"bytes": 1024,
"row_count": 5
}
]
}
You can find the
guid
for each table object in the "results"
array.As you can see from the response body, the
/tables
endpoint supports pagination for larger response sets.The
"results"
table objects in the GET /tables/
endpoint (as seen in the previous subsection) contain a field updated_on
, which reflects the last time a particular object was changed.In order to see the latest changes to a set of metadata objects such as databases, schemas, tables, or columns, use the query parameter with the format
updated_on__gte
(i.e. for greater-than or equals). The gte
can be replaced with lte
, gt
, lt
as appropriate. As an example, see the docs for the tables endpoint.Note that
updated_on
reflects the last change for an object (i.e. its description was changed or was ingested), but the field last_updated_on
reflects the last time an object was ingested from the data source only.With guids in hand, you can read the metadata of individual tables.
The endpoint is now:
GET /metadata/:guid/
And the curl command would be:
curl -H "Authorization: Token <your_token>" https://api.production.selectstar.com/v1/metadata/<your_guid>/
You should get back a response that looks like:
{
"object_type": "table",
"guid": "ta_UUyFgbgRhVqhhHa5WCjBaa",
"name": "sales",
"description": "global sales",
"search_name": "dwh.analytics.sales",
"data_type": "table",
"data_source_type": "snowflake",
"url": "string",
"tags": [
{
"guid": "ta_UUyFgbgRhVqhhHa5WCjBaa",
"type": "category",
"name": "Orders",
"icon": "tagBlue",
"color": "#33b1ff"
}
]
}
That's it for reading from endpoints!
Writing is a little more involved than reading. Although the endpoint is the same, you'll need to tell your client to send a
PATCH
request, as well as a body of data that lets the Select Star API know what data to update with.The endpoint is:
PATCH /metadata/:guid/
and the payload is JSON (which may require you to set the
content-type
header as in the curl command):{
"description": "new description here"
}
Put together, the curl command is:
curl \
-H "Authorization: Token <your_token>" \
-H "content-type: application/json" \
--data '{"description": "global sales for last quarter"}' \
-X PATCH \
https://api.production.selectstar.com/v1/metadata/<your_guid>/
The response will look just like the
GET
request response, except your description will have been updated.{
"object_type": "table",
"guid": "ta_UUyFgbgRhVqhhHa5WCjBaa",
"name": "sales",
"description": "global sales for last quarter",
"search_name": "dwh.analytics.sales",
"data_type": "table",
"data_source_type": "snowflake",
"url": "string",
"tags": [
{
"guid": "ta_UUyFgbgRhVqhhHa5WCjBaa",
"type": "category",
"name": "Orders",
"icon": "tagBlue",
"color": "#33b1ff"
}
]
}
That's all for the basics of using the Select Star API! If you have any questions, please don't hesitate to reference the API Reference Documentation and be sure to check out the API Examples
Last modified 6h ago