Getting Started

Getting Started Guide

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.

Client

Any http client can be used to make calls to the API. For usage in a script, you may choose a library like requests for Python or axios for Node. For one-off testing, you might use something like Postman.

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.

Postman

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.

Download and Import Select Star's Collection

1. Download and install the client from their website: https://www.postman.com/

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.

Configure Authentication

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.

Other tips

• Postman also has a Documentation menu that will show you the documentation within their UI.

• You can use tools like JSON Editor Online to view, manipulate and export responses.

• Postman offers a code export version that will help you craft your scripts once you have configured the API call you need.

Authentication

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.

Advanced example

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!

Read a List of Tables

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.

Filtering by updated_on

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.

Read a Table

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!

Write Descriptions to a Table

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"
        }
    ]
}

Wrap-up

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