REST API for Unstructured Data Support

This topic describes the REST API used to access staged files.

In this Topic:

GET /api/files/

Retrieves (downloads) a data file from an internal or external stage.

Authentication

Authenticate to the REST API endpoint using OAuth for custom clients. Create a security integration (using CREATE SECURITY INTEGRATION) to enable an HTTP client that supports OAuth (such as cURL) to redirect users to an authorization page and generate access tokens for access to the REST API endpoint. For information on configuring OAuth for custom clients, see Configure Snowflake OAuth for Custom Clients.

Usage Notes

  • Send the scoped URL or file URL for a staged file in the GET request.

    • Generate a scoped URL by calling the BUILD_SCOPED_FILE_URL SQL function.

      Note

      Scoped URLs are not supported yet. This URL type is targeted for availability in the near term. When available, this support will be announced in the release notes.

    • Generate a file URL by calling the BUILD_STAGE_FILE_URL SQL function. Alternatively, query the directory table for the stage, if available.

  • Authenticate to Snowflake via the Snowflake SQL API using OAuth or key pair authentication. For instructions, see Snowflake SQL API Developer Guide.

  • The authorization to access files differs depending on whether a scoped URL or file URL is sent in the GET request:

    Scoped URL

    Only the user who generated the scoped URL can use the URL to access the referenced file.

    File URL

    Any role that has sufficient privileges on the stage can access the file:

    • External stage: USAGE

    • Internal stage: READ

  • An HTTP client that sends a URL (either scoped URL or file URL) to the REST API must be configured to allow redirects.

Request Headers

The following request headers apply to all operations:

Header

Description

Authorization

Set this to Bearer, followed by the generated OAuth token used to authenticate to Snowflake.

For more information, see Authenticating to the Server Using OAuth.

For example:

Authorization: Bearer token

Accept

Set this to */*).

User-Agent

Set this to the name and version of your application (e.g. applicationName/applicationVersion). You must use a value that complies with RFC 7231.

X-Snowflake-Authorization-Token-Type

Set this to OAUTH.)

Example

The following Python example issues an HTTP request for client myApplication version 1.0:

import requests
response = requests.get(url,
    headers={
      "User-Agent": "reg-tests",
      "Accept": "*/*",
      "X-Snowflake-Authorization-Token-Type": "OAUTH",
      "Authorization": """Bearer {}""".format(token)
      },
    allow_redirects=True)
print(response.status_code)
print(response.content)