Getting Started
Last updated
Was this helpful?
Last updated
Was this helpful?
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/.
Any http client can be used to make calls to the API. For usage in a script, you may choose a library like for Python or for Node. For one-off testing, you might use something like .
This guide will walk you through two different examples:
Using Postman, which is more interactive or user friendly, if you are not so familiar with coding just yet.
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.
Import the collection into postman
Use the shortcut ⌘+O or click the Import button at the top left.
Choose file downloaded Select Star API Postman Collection.json
Click import
Your postman collection is now ready to test and generate code snippets.
In Postman, configure the Authentication at the root level folder for Select Star API
Click on the root folder Select Star API.
Go to the Authorization tab
Choose API Key in the Type dropdown
Insert "Authorization" for the Key input.
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:
In curl you can set the header using the -H flag:
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:
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.
(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)
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.
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:
And the curl command would be:
You should get back a response that looks like:
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:
and the payload is JSON (which may require you to set the content-type header as in the curl command):
Put together, the curl command is:
The response will look just like the GET request response, except your description will have been updated.
Download and install the client from their website:
Download our . This collection contains all available endpoints in our . And will help you test them out effortlessly
Go to the 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.
Insert "Token {{apiKey}}". Here, {{apiKey}} can be the raw token you copied earlier, or you can chose to use .
You can use tools like to view, manipulate and export responses.
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 endpoint.
That's all for the basics of using the Select Star API! If you have any questions, please don't hesitate to reference the and be sure to check out the
