# 

## Overview

Paradise Gateway provides a RESTful JSON API that works with any HTTP client. While there is no mandatory SDK, using a typed client library can reduce boilerplate, handle authentication, and provide IDE autocompletion.

## Direct API integration

Every endpoint in the Paradise Gateway API accepts standard JSON over HTTPS. You can integrate using any language's built-in HTTP client:

| Language | Recommended HTTP client |
|  --- | --- |
| Python | `requests` or `httpx` |
| JavaScript / TypeScript | `fetch` (built-in) or `axios` |
| C# | `HttpClient` (`System.Net.Http`) |
| Java | `java.net.http.HttpClient` (JDK 11+) |
| Go | `net/http` (stdlib) |
| PHP | `curl` or `guzzlehttp/guzzle` |
| Ruby | `net/http` (stdlib) or `faraday` |


## Authentication setup

All SDK examples assume you store your API key in an environment variable.

Python
```python
import os
import requests

API_KEY = os.environ["PARADISE_API_KEY"]
BASE_URL = os.environ.get("PARADISE_BASE_URL", "https://api.dev.paradisegateway.net")

session = requests.Session()
session.headers.update({
    "Content-Type": "application/json",
    "APIKEY": API_KEY,
})

resp = session.get(f"{BASE_URL}/v1/transactions?take=5")
print(resp.json())
```

JavaScript
```javascript
const API_KEY = process.env.PARADISE_API_KEY;
const BASE_URL = process.env.PARADISE_BASE_URL || "https://api.dev.paradisegateway.net";

async function apiRequest(path, options = {}) {
  const resp = await fetch(`${BASE_URL}${path}`, {
    ...options,
    headers: {
      "Content-Type": "application/json",
      "APIKEY": API_KEY,
      ...options.headers,
    },
  });
  if (!resp.ok) throw new Error(`API error: ${resp.status}`);
  return resp.json();
}

const transactions = await apiRequest("/v1/transactions?take=5");
console.log(transactions);
```

C#
```csharp
using System.Net.Http;

var apiKey = Environment.GetEnvironmentVariable("PARADISE_API_KEY")!;
var baseUrl = Environment.GetEnvironmentVariable("PARADISE_BASE_URL")
    ?? "https://api.dev.paradisegateway.net";

using var client = new HttpClient { BaseAddress = new Uri(baseUrl) };
client.DefaultRequestHeaders.Add("APIKEY", apiKey);

var resp = await client.GetStringAsync("/v1/transactions?take=5");
Console.WriteLine(resp);
```

Java
```java
import java.net.http.*;
import java.net.URI;

String apiKey = System.getenv("PARADISE_API_KEY");
String baseUrl = System.getenv().getOrDefault(
    "PARADISE_BASE_URL", "https://api.dev.paradisegateway.net");

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create(baseUrl + "/v1/transactions?take=5"))
    .header("APIKEY", apiKey)
    .GET().build();
HttpResponse<String> resp = client.send(request,
    HttpResponse.BodyHandlers.ofString());
System.out.println(resp.body());
```

Go
```go
package main

import (
    "fmt"
    "io"
    "net/http"
    "os"
)

func main() {
    apiKey := os.Getenv("PARADISE_API_KEY")
    baseURL := os.Getenv("PARADISE_BASE_URL")
    if baseURL == "" {
        baseURL = "https://api.dev.paradisegateway.net"
    }

    req, _ := http.NewRequest("GET", baseURL+"/v1/transactions?take=5", nil)
    req.Header.Set("APIKEY", apiKey)
    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()
    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}
```

PHP
```php
$apiKey = getenv("PARADISE_API_KEY");
$baseUrl = getenv("PARADISE_BASE_URL") ?: "https://api.dev.paradisegateway.net";

$ch = curl_init("$baseUrl/v1/transactions?take=5");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Content-Type: application/json",
        "APIKEY: $apiKey",
    ],
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
```

Ruby
```ruby
require "net/http"
require "json"

api_key = ENV.fetch("PARADISE_API_KEY")
base_url = ENV.fetch("PARADISE_BASE_URL", "https://api.dev.paradisegateway.net")

uri = URI("#{base_url}/v1/transactions?take=5")
req = Net::HTTP::Get.new(uri, {
  "Content-Type" => "application/json",
  "APIKEY" => api_key,
})
resp = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(req)
end
puts JSON.parse(resp.body)
```

## OpenAPI specification

The Paradise Gateway API is described by an [OpenAPI 3.1](https://spec.openapis.org/oas/v3.1.0) specification. You can use it to:

* **Generate typed clients** with tools like [openapi-generator](https://openapi-generator.tech/) or [openapi-typescript](https://github.com/drwpow/openapi-typescript)
* **Import into API platforms** like Postman, Insomnia, or Bruno
* **Validate requests** in your CI/CD pipeline


### Generate a client library

Bash
```shell
# TypeScript client
npx openapi-typescript apis/openapi.yaml -o src/api-types.ts

# Python client
openapi-generator-cli generate \
  -i apis/openapi.yaml \
  -g python \
  -o ./paradise-client-python

# Java client
openapi-generator-cli generate \
  -i apis/openapi.yaml \
  -g java \
  -o ./paradise-client-java
```

PowerShell
```powershell
# TypeScript client
npx openapi-typescript apis/openapi.yaml -o src/api-types.ts

# Python client
openapi-generator-cli generate `
  -i apis/openapi.yaml `
  -g python `
  -o ./paradise-client-python

# Java client
openapi-generator-cli generate `
  -i apis/openapi.yaml `
  -g java `
  -o ./paradise-client-java
```

## Postman collection

Import the OpenAPI spec directly into Postman:

1. Open Postman and select **Import**.
2. Choose the `apis/openapi.yaml` file or paste the spec URL.
3. Postman generates a collection with all endpoints, example payloads, and authentication pre-configured.
4. Set the `APIKEY` variable in your environment.


## Best practices

* **Store API keys in environment variables** — never hard-code them in source files.
* **Set a base URL variable** — switch between sandbox and production without code changes.
* **Handle errors consistently** — check `response_status` and `response_code` on every response.
* **Use the `correlation_id`** — log it for every request; include it in support tickets.
* **Implement retry logic** — retry on `5xx` errors with exponential backoff. See [Integration best practices](/docs/get-started/integration-best-practices).


## Next steps

* [Quickstart](/docs/get-started/quickstart) — make your first API call
* [Quick reference](/docs/reference/quick-reference) — endpoint cheat sheet and test data