# Introduction/Getting Started

## Base URL

> <https://data-sources-v2.pdap.io/api> ← builds from main branch
>
> <https://data-sources-v2.pdap.dev/api> ← builds from dev branch

## Endpoints & Models

Navigate to either base URL above to see the API and model reference for v2 API on either the `main` or `dev` branch.

This documentation assumes you are familiar with programming languages such as Python, as well as the big-picture functionality of the API. For a more thorough breakdown of the functionality of an API, consider documentation such as Postman's [Beginner's Guide to APIs](https://www.postman.com/what-is-an-api/#how-do-apis-work).

Reach out to <contact@pdap.io> or make noise in [Discord](https://discord.gg/wMqex8nKZJ) if you have questions.

## Overview

The PDAP API is how internal and external users programmatically access information and make changes to the PDAP Data Sources database.

## Getting Access

Logged-in and authenticated users can get access to the API.

## Authentication

The majority of API routes require one of two forms of Authentication: API Tokens, and JSON Web Tokens (JWTs). A limited number of endpoints allow one or the other.

#### API Tokens

* API tokens are long-lived tokens used for endpoints with low security needs that do not modify existing data, such as `GET` requests.
* API tokens can be passed to accepting endpoints using `Basic` authorization (i.e., `Basic <TokenName>`).
* API tokens can be obtained by using the `/api-key` endpoint and generating login credentials
* API tokens are long-lived, and users can only have one active at a time.

#### JSON Web Tokens (JWTs)

* [JWTs](https://en.wikipedia.org/wiki/JSON_Web_Token) are short-lived encrypted tokens used for more secure endpoints
* JWTs can be passed to accept endpoints using `Bearer` authorization (i.e. `Bearer <TokenName>`)
* An `access_token` and `refresh_token` are both generated by the `/login` and `/login-with-github` endpoints
  * The access token is the token to be used for most endpoints
* Separate single-purpose JWTs are used for specific endpoints, such as `/reset-password`

## Rate limits

Different endpoints have different rate limits to them, with endpoints like `/data-sources/{resource_id}` `GET` Being more generous than endpoints such as `/login`. This helps prevent abuse of the system, and should minimally impact normal usage.

## Examples

{% tabs %}
{% tab title="Python" %}
**GET Agencies**

```python
import requests
base_url = "https://data-sources-v2.pdap.io/"
api_key = "YOUR_API_KEY_HERE"  # Replace with your actual API key

url = f"{base_url}agencies"

# Create the Authorization header
headers = {
    "Authorization": f"Bearer {api_key}"
}

# Make the GET request with the Authorization header
response = requests.get(url, headers=headers)
```

{% endtab %}

{% tab title="JavaScript" %}

#### GET agencies

```javascript
const axios = require('axios');

const baseUrl = "https://data-sources-v2.pdap.io/";
const api_key = "YOUR_API_KEY_HERE";  // Replace with your actual API key

const url = `${baseUrl}agencies`;

// Create the Authorization header
const headers = {
  'Authorization': `Bearer ${api_key}`
};

// Make the GET request with the Authorization header
axios.get(url, { headers })
  .then(response => {
    console.log("Search results:");
    response.data.forEach(item => {
      console.log(`Agency: ${item.name}`);
    });
  })
  .catch(error => {
      console.error("An error occurred:", error.message);
    }
  });
```

{% endtab %}
{% endtabs %}