Get Started
Tips and tricks for using the Secoda APIs.
The Secoda API is based around REST principals. You will need a Bearer token to use the API - see the authentication page for instructions on how to create your token.
Base URL
See below for the Base URL for your workspace.
app.secoda.co
api.secoda.co
eu.secoda.co
eapi.secoda.co
apac.secoda.co
aapi.secoda.co
If your workspace is associated with a unique URL, then the Base URL for the API is formed by appending api/v1/
to the end of your workspace's URL.
Test the Base URL
Make a request to the Secoda Health Check API endpoint /healthcheck
. A successful response should look like this.
Pagination
The API response includes several key components relevant to pagination:
links
: Contains URLs for the next and previous pages.meta
: Provides metadata including the current page, previous page, and next page numbers.count
: The total number of items in the dataset.total_pages
: The total number of pages available.results
: An array of objects, each representing a data item.
Initial Request
To start retrieving data, make a request to the API endpoint. If no page is specified, the first page of results is returned by default.
Navigating Pages
Next Page: To move to the next page, use the URL provided in the
links.next
field. If this field isnull
, it indicates you are on the last page.Previous Page: To return to the previous page, use the URL in the
links.previous
field. A value ofNone
indicates you are on the first page.Specific Page: To request a specific page, modify the request URL to include the desired page number as a query parameter (e.g.,
?page=3
).
Handling Pagination in Client Code
Check Pagination Links: Always check the
links.next
field to determine if additional pages are available.Loop Through Pages: If automating data retrieval, loop through pages by making subsequent requests using the URL in
links.next
until it isnull
.Access Page Metadata: Utilize the
meta
field to present navigation controls or information about the current page status in your application UI.
Example Code Snippet
Here's a simplified example in Python using the requests
library to navigate through pages:
Catalog Filters
To list resources in your workspace with fine-grained control over filtering and sorting, you can use the resource/catalog
endpoint from Secoda. This endpoint allows you to customize the response by providing a serialized JSON object, URL encoded, as a query parameter in your request.
To generate the JSON object, you can use our API filter generator in your Settings page.
If you'd like to build your filters from scratch, refer to the JSON documentation for detailed information on the JSON structure, and the file linked below for how to utilize this request. The linked file is a sample Jupyter Notebook that demonstrates how to retrieve all resources that are Tables, Views, Dashboards, or Workbooks, which contain "customers" in the title. The results are sorted in descending order based on the last update time of the resource.
Note: This script linked does not account for pagination. Please see the pagination section above for guidance around implementing this as part of your script.
Last updated