Pure API: Extracting Person Dependents Using PythonPure API: Extracting Person Dependents Using Python

Requirements

• Pure Admin Account 
• Valid API Key 
• API Documentation
• Python

Expertise Level

Knowledge of Python is required. See also Python API Requests: Fundamental Coding Examples 

High-Level Process

1. Read the listing of Person UUIDs from a CSV file.
2. Fetch the Person details (first name, last name).
3. Retrieve the dependent data for each person.
4. Fetch the details of each dependent (e.g., Activity, Award, Prize, Research Output).
5. Export the dependent details to JSON file format for each dependent using the naming convention person_firstname_lastname_systemName_dependentUUID.json, organized into folders named after each person's UUID.

# -*- coding: utf-8 -*-
"""
Created on Mon Feb 10 09:07:04 2025
@author: mlr
"""
import requests
import csv
import json
import os

API_KEY = 'YourAPIKeyHere'
BASE_URL = 'https://YourPureURL/ws/api/'

ENDPOINTS = {
   "Activity": "/activities/{uuid}",
   "Application": "/applications/{uuid}",
   "Award": "/awards/{uuid}",
   "DataSet": "/data-sets/{uuid}",
   "Equipment": "/equipment/{uuid}",
   "Prize": "/prizes/{uuid}",
   "Project": "/projects/{uuid}",
   "ResearchOutput": "/research-outputs/{uuid}",
   "StudentThesis": "/student-theses/{uuid}"
   # double check your Pure API documentations, additional endpoint may be needed e.g. Press-media
}

def get_person_details(person_uuid):
    """Fetches the person's first and last name using the UUID."""
    url = f"{BASE_URL}/persons/{person_uuid}"
    headers = {
        'accept': 'application/json',
        'api-key': API_KEY
    }

    response = requests.get(url, headers=headers)

    if response.status_code == 200:
        person_data = response.json()
        first_name = person_data.get('name', {}).get('firstName', 'Unknown')
        last_name = person_data.get('name', {}).get('lastName', 'Unknown')
        return first_name, last_name
    else:
        print(f"Error fetching person details for UUID {person_uuid}")
        return None, None

def fetch_person_dependents(person_uuid, first_name, last_name):
    """Fetches dependents of a person and saves details as JSON in a directory named after the person's UUID."""
    url = f"{BASE_URL}/persons/{person_uuid}/dependents"
    headers = {
        'accept': 'application/json',
        'api-key': API_KEY
    }

    response = requests.get(url, headers=headers)

    if response.status_code == 200:
        dependents_data = response.json().get('items', [])

        # Create a directory for the person based on UUID
        person_dir = os.path.join(os.getcwd(), person_uuid)
        os.makedirs(person_dir, exist_ok=True)

        for dependent in dependents_data:
            system_name = dependent.get('systemName', 'Unknown')
            dependent_uuid = dependent.get('uuid', 'Unknown')

            if system_name in ENDPOINTS:
                dependent_url = BASE_URL + ENDPOINTS[system_name].format(uuid=dependent_uuid)
                dependent_response = requests.get(dependent_url, headers=headers)

                if dependent_response.status_code == 200:
                    dependent_details = dependent_response.json()

                    # File naming: firstname_lastname_systemName_dependentUUID.json
                    file_name = f"{first_name}_{last_name}_{system_name}_{dependent_uuid}.json"
                    file_path = os.path.join(person_dir, file_name)

                    # Save JSON file
                    with open(file_path, 'w', encoding='utf-8') as json_file:
                        json.dump(dependent_details, json_file, indent=4)
                    print(f"Saved data for {system_name} in {file_path}")
                else:
                    print(f"Error fetching {system_name} details for UUID {dependent_uuid}")
            else:
                print(f"Skipping unsupported systemName: {system_name}")
    else:
        print(f"Error fetching dependents for person UUID {person_uuid}")

def main():
    """Reads 'person.csv', retrieves each person's name, and saves dependent data in a structured folder format."""
    with open('person.csv', 'r', encoding='utf-8') as csvfile:
        reader = csv.DictReader(csvfile)

        for row in reader:
            person_uuid = row['uuid'].strip()  # Ensure no leading/trailing spaces
            if not person_uuid:
                continue  # Skip empty UUIDs
            
            first_name, last_name = get_person_details(person_uuid)

            if first_name and last_name:
                fetch_person_dependents(person_uuid, first_name, last_name)

if __name__ == "__main__":
    main()

Process Breakdown

1. Reading Input (CSV):
   1. The script starts by reading a CSV file (person.csv), which contains a list of people identified by their unique uuid.
   2. For each person in the CSV, the script retrieves their uuid to fetch further details.
2. Fetching Person Details:
   1. For each uuid, the script sends a GET request to the /persons/{uuid} endpoint.
   2. The API response contains the person's firstName and lastName, which are extracted and stored for later use.
   3. If the request is successful, the script continues; if not, an error message is printed, and the process moves to the next person.
3. Fetching Dependent Data:
   1. The script then sends another GET request to the /persons/{uuid}/dependents endpoint to retrieve a list of dependents associated with the person.
   2. The dependents are returned as a list of items, each containing information about the dependent type (systemName) and its unique identifier (uuid).
   3. For each dependent, the script determines its type based on the systemName field. If the type matches any of the predefined types in the script (such as ResearchOutput, Prize, Award, etc.), the script proceeds to fetch additional details about that dependent.
4. Fetching Dependent Details:
   1. The script then makes a GET request to the relevant endpoint based on the systemName of the dependent (e.g., /research-outputs/{uuid}, /projects/{uuid}).
   2. Each dependent's details are returned as JSON data, which is then saved to a separate file using the naming convention person_firstname_lastname_systemName_dependentUUID.json.
   3. JSON files for each person are saved inside a dedicated folder named after their UUID (uuid), making them easy to read and parse later.
5. Handling Errors and Unsupported Dependents:
   1. If a systemName is encountered that is not part of the predefined list in the script, the dependent is skipped, and a message is logged indicating the unsupported type.
   2. If any of the API requests for person details or dependent data fail, the script prints an error message and moves on to the next item.
6. Output:
   1. For each dependent successfully fetched, a corresponding JSON file is created and saved with relevant details.
   2. JSON files are organized within folders named after each person's UUID (uuid).
   3. The naming convention for each file is person_firstname_lastname_systemName_dependentUUID.json to ensure easy identification.

Customer Benefits

• Automation: This script fully automates the process of retrieving and storing dependent data associated with a person, saving manual effort.
• Dynamic: It supports multiple dependent types (such as Research Outputs, Projects, and Prizes, Activities, Award, Application, Dataset, Equipment, Project, Student Thesis) without requiring further customization for each type.
• Scalability: The script processes as many people from the CSV file as needed, handling multiple records in a single execution.
• Easy-to-Use Outputs: The JSON files are easy to parse and integrate into other systems or processes for further analysis or reporting.

Use Case Example:

If the customer has a list of people (identified by uuid), they can simply provide that list in a CSV format. The script will automatically fetch the associated details and dependent data (e.g., publications, awards, projects) for each person and save the data in a structured JSON format, ready for further analysis or integration. Ref: 00978439