How To Use the SeaLights Public API Collection

Owned by Samantha Gray
Last updated: May 02, 2024
5 min read

Using the SeaLights Public API Postman Collection

This guide will walk you through using the Postman collection provided for our public API. The collection utilizes environment variables to streamline your requests.

Target Audience

This guide is intended for users with a basic understanding of Postman and API interactions.

Prerequisites

Note: Throughout this guide, we'll use the term "env file" to refer to the Postman environment file.

Importing the Collection

  1. Navigate to our Public API Documentation.

  2. Locate the "Run in Postman" button and click it.

    • Select your preference: Postman for Web or the Postman Desktop Client.

      Screenshot 2024-04-30 at 16.36.39.png
      In this example, we’ll select Postman for Web

  3. Select the workspace into which you want to import the collection and click “Import”

    Screenshot 2024-04-30 at 16.47.22.png
    In this example, we’re importing to a workspace named Demo

Setting Up Your Environment

  1. In the Postman sidebar, select Environments. Right-click on the pre-populated environment named "Demo Env" and select Duplicate.

  2. Right-click on "Demo Env Copy" and select Rename.

  3. Choose a descriptive name for your environment (e.g., "CompanyName Env") and save. This will allow you to keep our demo environment file as a boilerplate, should you ever need to create more than one Postman environment.

  4. At the top right of the Postman workspace, click the environment selection dropdown. (If you don't have another environment already set, this will say "No Environment".) Select your new environment "CompanyName Env" from the list.

Next, we'll walk through setting the value of your variables in your new environment

Understanding Environment Variables

The provided "Demo Env" includes several pre-defined variables. THREE of these variables are required for basic API interaction.

  • SL_DOMAIN: This variable holds the base URL for our API. Be sure to remove a trailing slash from your URL!

    • e.g. https://your-domain.sealights.co

  • SEALIGHTS_API_TOKEN: Found in your SeaLights UI (/settings/tokens/api-tokens).

    • Click the Gear Icon to access Settings >> From left sidebar: Integration >> API Tokens

  • SEALIGHTS_AGENT_TOKEN: Found in your SeaLights UI (/settings/tokens/agent-tokens).

    • Click the Gear Icon to access Settings >> From left sidebar: Cockpit & Onboarding >> Agent Tokens

IMPORTANT: The remaining variables in the "Demo Env" are for demonstration and documentation purposes only. These variables represent query parameters or path variables specific to individual API requests. It's generally recommended to set these directly within each request, not globally in the environment.

 

Once you have updated your new environment file with these three variables, uncheck the remaining variables in the environment file. This will guard against using “dummy” information throughout the collection. Click “Save” near the top right.

Using Multiple Environments

Postman allows you to manage and switch between multiple environment files. This is useful for testing different API configurations or managing access for various accounts.

In the Postman sidebar, navigate to the Environments tab. Click the Manage Environments button (gear icon). Here you can create additional environment files from our boilerplate, using the same "duplicate and rename" process we used at the beginning of this guide.

Tip: Users who need to interact with multiple SeaLights instances, should consider creating a dedicated environment file with only the relevant variables for each instance. This helps maintain organization and clarity.

Additional Considerations

  • Security: It's crucial to safeguard your API Key. Avoid committing it to public repositories like version control systems.

  • Updates: We may occasionally update the Postman collection structure or environment variables. Refer to our API documentation for the latest version.

By following these steps and understanding environment variable usage, you'll be well on your way to efficiently interacting with our Public API using Postman.

 

Working with the Collection

  1. Click on Collections in the left sidebar to return to your imported collection.

  2. Select your newly created environment from the dropdown at the top right of the Postman window (if not already set)

Using Requests:

  • The collection's requests will now utilize the SL_DOMAIN, SEALIGHTS_API_TOKEN, and SEALIGHTS_AGENT_TOKEN you defined in your environment.

  • Each request may have additional query parameters and/or path variables. These can be updated within the request's Parameters tab.

  • Only query parameters that are “checked” will be sent with the request

  • Path variables are always sent with the request

  • NOTE: The value of variables is not shown in the URL string, but if the variable is set, it will be used when the request is sent. For this reason, in the screenshot above, the value of :appName has not been replaced by “DemoApp”, but the query parameter of “offset” is being sent with a value of “3”

REMEMBER: Throughout the collection, variables other than the “Top 3” (such as {{branch_name}} or {{bsid_var}}) may be referenced in query parameters and path variables. These are ONLY PLACEHOLDERS. Feel free to overwrite them - they do not need to be managed at the Environment level.

“In-Context” Documentation

Using the “paper” icon found on the right toolbar will reveal additional API documentation without leaving Postman’s interface.

This documentation is context sensitive: what is revealed is based on the endpoint/request you have open.