API Basics

Introduction

Sunlight provides a powerful and flexible API that allows you to integrate Sunlight's functionality into your application. Whether you're performing card switches, managing customizations, or configuring webhooks, the Sunlight API offers a wide range of capabilities to enhance your user experience. In this guide, we'll provide a high-level overview of how to work with Sunlight APIs, including authentication, versioning, and error handling.

Authentication

All Sunlight API requests require authentication using an API key and a secret key. These keys are used to identify and authorize your application when making requests to the Sunlight API.

To obtain your API credentials, please reach out to us at [email protected]

When making an API request, you must include the following headers for authentication:

"x-api-key: YOUR_API_KEY"
"x-secret-key: YOUR_SECRET_KEY"

Additionally, you need to specify the API version you wish to use. The default version is 1. Use the following header to specify the version:

"x-version: 1"

Example

Here's an example of an authenticated API request using curl:

curl --request GET \
     --url https://api.sunlightapi.com/api/customizations/list \
     --header 'accept: application/json' \
     --header 'x-api-key: <YOUR-API-KEY>' \
     --header 'x-secret-key: <YOUR-SECRET-KEY>' \
     --header 'x-version: 1'

Error Handling

When working with the Sunlight API, it's important to handle errors appropriately. The API may return error responses with specific error codes and messages. The error response is provided in JSON format with the following structure:

{
  "error_code": string,
  "error_message": string
}

Below, we've grouped the possible error responses by their corresponding HTTP status codes. Each error is described by its error_code and error_message.

400 Bad Request

401 Unauthorized

429 Too Many Requests

You can use this information to diagnose failed transactions and fine-tune your exception-handling capabilities. By understanding the different error codes and messages, you can provide meaningful feedback to users and handle errors gracefully in your application.

Versioning and Backwards Compatibility

The Sunlight API is designed with versioning and backwards compatibility in mind. We strive to avoid making breaking changes to the API without reaching out to you first. We're continually making backwards-compatible changes to the API. Examples of things we do not consider "breaking" include:

• Adding new optional request parameters to existing API methods.
• Adding new properties to existing API responses.
• Changing the order of properties in existing API responses.
• Adding new API resources or methods.
• Changing the length or format of opaque strings, such as resource IDs, error messages, and other human-readable strings.