Knowledge Base

Introduction to the Narrative API

Introduction to the Narrative Data Collaboration Platform API

The Narrative API is a RESTful API designed to enable seamless data collaboration. This document provides an introduction to the Narrative API, outlining authentication methods, documentation resources, and best practices for using the API.

Overview

  • RESTful Architecture
    Narrative’s API is organized around REST principles. It features:
    • Predictable, resource-oriented URLs
    • JSON-encoded responses
    • Standard HTTP response codes and methods (verbs)
    • Form-encoded request bodies
  • Base URL
    The production base URL for the API is:
    https://api.narrative.io
  • Learn More
    To learn more about the Narrative Data Collaboration Platform in general, please see the Platform Knowledge Base: https://kb.narrative.io/.

API Service Documentation

You can find the complete, detailed OpenAPI documentation (for the latest versions of all services) here:

https://api.narrative.dev/

Authentication

Bearer Authentication

The Narrative API uses bearer tokens for authentication.

  • You can create tokens with granular read/write permissions that align with the specific API services you intend to use.
  • Tokens should be kept secure and never exposed in public repositories or client-side code.

Authentication Requirements

With a few exceptions, only users and applications authorized by Bearer Auth tokens may make API calls to the Narrative API.

Creating a Token

You can create a token using the Narrative Platform UI. Read more here NEEDS LINK

Example: Using cURL with Environment Variables

export DATASET_ID=12345
export TOKEN="YOUR_BEARER_TOKEN"

curl -vvv --request GET \
  --url https://api.narrative.io/datasets/${DATASET_ID} \
  --header "Authorization: Bearer ${TOKEN}" \
  --header "Content-Type: application/json"

In this example, two environment variables (DATASET_ID and TOKEN) are used to keep sensitive information out of the command

Best Practices

  1. Rate Limits
    • Narrative does not currently enforce customer-facing API limits, but reserves the right to add them in the future. Please avoid calling the API from multiple services simultaneously, or attempting to call the API directly from client-side code.
  2. Avoid Excessive or Distributed Direct Calls
  • Please avoid calling the API from multiple services simultaneously or in a distributed manner, and do not call the API directly from client-side code. Instead:
    1. Use an API proxy layer to consolidate and manage requests.
    2. Implement a caching mechanism to reduce redundant calls.
    3. Include retry logic in case you approach or exceed any future rate limits.
  1. Granular Permissions
    • When creating bearer tokens, limit permissions to the minimum required for your use case. This follows the principle of least privilege and helps keep your data secure.
  2. Versioning
    • Pay attention to API version information in the OpenAPI docs. Backwards-incompatible changes (if any) are typically communicated in advance (see Breaking Changes).

Breaking Changes

As our API is in Open Beta, Narrative reserves the right to make updates to the API when necessary, including Breaking Changes. However, we will make every effort to adhere to the following standards:

  1. API Versioning
    • Any breaking changes will be introduced as a new, versioned endpoint (e.g., /v2/ or /v2.1/).
    • To avoid being impacted by a breaking change, you should version your API calls where versions are implemented in the documentation.
  2. Advance Notice
    • We will make a best effort to provide 30 days’ notice of any breaking change, giving you time to adjust your integrations as needed.

Support and Resources

< Back
Rosetta

Hi! I’m Rosetta, your big data assistant. Ask me anything! If you want to talk to one of our wonderful human team members, let me know! I can schedule a call for you.