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.

Reach out to [e-mail] or make noise in Discord 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 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

Python

GET Agencies

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)

JavaScript

GET agencies

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);
    }
  });