Connecting Your API

Data sources are the bridge between your backend and NativeSuite. This guide covers creating data sources, configuring authentication, and mapping your API response.

Creating a Data Source

1. Navigate to your app and go to Data Sources
2. Click Create Data Source
3. Fill in the configuration:

Field	Description
Name	A descriptive name (e.g., "Revenue Stats", "User Orders")
Endpoint URL	The full URL of your REST API endpoint
HTTP Method	GET, POST, etc.
Headers	Any custom headers your API requires

Endpoint Authentication

This is how NativeSuite authenticates with your API (not how your end users authenticate — that's configured separately in Authentication Providers).

Common patterns:

Bearer Token

Authorization: Bearer your-api-token

API Key Header

X-API-Key: your-key

Custom Headers

Add any headers your API expects. NativeSuite sends these with every request to your endpoint.

Response Mapping

After configuring the endpoint, NativeSuite fetches a sample response and displays the JSON structure. You then select which fields to make available for widgets.

How It Works

Given this API response:

{
  "data": {
    "revenue": {
      "total": 48290,
      "currency": "USD",
      "change_percent": 12.4
    },
    "orders": {
      "count": 142,
      "pending": 8
    }
  },
  "updated_at": "2026-04-15T10:30:00Z"
}

You'd map fields like:

• data.revenue.total → available as revenue_total
• data.revenue.change_percent → available as revenue_change
• data.orders.count → available as order_count

These mapped fields become available when configuring widgets.

Nested Data

NativeSuite supports deeply nested JSON. Use dot notation to reference nested fields. Arrays are also supported — useful for list and table widgets.

Array Responses

If your endpoint returns an array (e.g., a list of orders), the entire array is available for list and table widgets. Each item's fields can be mapped individually.

Dynamic URLs

If your endpoint URL needs to include user-specific data (like a user ID), NativeSuite handles this through the authentication layer. The end user's auth credentials are passed through to your API, so your endpoint can return personalized data.

Testing Your Data Source

After creating a data source, use the test functionality in the dashboard to verify:

1. The endpoint is reachable
2. Authentication works
3. The response structure matches what you expect
4. Your field mapping extracts the right values

Updating Data Sources

Data sources are shared across all releases. When you update a data source:

• The endpoint URL, auth, and mapping update immediately
• All widgets using this data source pick up the changes
• No need to create a new release for data source changes

WARNING

Changing field names in your response mapping may break existing widgets that reference those fields. Update your widgets after renaming fields.

Best Practices

• Use stable endpoints — Don't point at endpoints that change structure frequently
• Return only what's needed — Smaller responses mean faster widget updates
• Include timestamps — Adding an updated_at field lets users know how fresh the data is
• Handle errors gracefully — Return meaningful error responses so NativeSuite can show appropriate states