Pure API Guide: Total Number of Projects with International Collaborating PartnersPure API Guide: Total Number of Projects with International Collaborating Partners

Requirements

This guide is intended for users with intermediate API experience who are already familiar with Pure API concepts and response structures.

• Ensure you have an active API key with access to the necessary endpoints (/projects, /external-organizations, etc.).
• Access permissions are defined via the access definition assigned to your API key.
• For information on how to create and configure API keys, refer to the API Key Setup Guide
• Knowledge of post-processing tools (e.g., Power BI, Excel, Python, etc.) to transform and sort output if needed.

API Endpoints Used

1. GET /projects
2. GET /external-organizations/{uuid}

Data Retrieval Process (via Pure API)

The process involves paging through projects, identifying those with external collaborators, and grouping them by institution.

1. Retrieve Projects Using Pagination

• Endpoint: GET /projects?size=100&offset=…
• Paged requests are used to fetch all available projects.
• Extract the uuid and the list of collaborators from each project.

2. Filter Collaborators for External Associations

• For each project, inspect the collaborators array.
• Filter collaborators where typeDiscriminator = "ExternalCollaboratorAssociation".
• These collaborators are associated with external organizations, not internal staff.

3. Resolve External Organization Names

• For each external collaborator, retrieve the organization’s name:
  • Endpoint: GET /external-organizations/{uuid}
  • Parse the "name.en_GB" or "name.en_US" field to obtain the readable name.
• Cache organization names to avoid repeated API calls.

4. Aggregate and Count

• Group the project UUIDs by external organization name.
• Count the number of distinct projects per collaborator.
• Compute the overall total number of projects that include at least one external partner.

5. Export Results (Optional)

• Though not required, results can be exported to .csv or .txt formats for easier distribution or analysis.
• Common columns:
  • Collaborator Name
  • Number of Distinct Projects

Post-Processing Logic

While the Pure API provides raw structured data, meaningful insights such as totals, rankings, or groupings are typically calculated client-side. Starting from step 2 in the retrieval process, the following logic serves as a practical reference for post-processing.

Identify External Collaborators

• Inspect each project's collaborators array.
• Filter for items where:
• typeDiscriminator == “ExternalCollaboratorAssociation”
• This indicates the collaborator is an external organization (not internal staff).

Track Project UUIDs by Collaborating Organization

• For each external collaborator:
  • Use a set to store unique project UUIDs.
  • This prevents overcounting in case of multiple mentions of the same project.
• Count the number of distinct projects per organization.

Calculate Overall Totals

• Maintain a separate counter:
  • Increment once per project if it includes at least one external collaborator.
  • This prevents overcounting in case of multiple mentions of the same project.
• Count the number of distinct projects per organization.

Calculate Overall Totals

• Maintain a separate counter:
  • Increment once per project if it includes at least one external collaborator.
  • This gives you the total number of projects with international collaborating partners.

1. Sort and Output Results (Optional)
   • Sort organizations by the number of projects (descending).
   • Export results to .txt, .csv, or other formats depending on reporting needs.
     • Columns: Collaborator Name, Number of Distinct Projects

Data Validation

To confirm the accuracy of the API-driven results, the final output will be validated against the equivalent details in Pure Admin’s Reporting module or Workspace. 

• For example:

• The aggregated result from the API (number of distinct projects with international collaborators).
• The corresponding total from the Pure Admin Project editor workspace.
• This comparison helps confirm
  • The reliability of the API data.
  • That the same filtering and grouping logic is applied outside the reporting module.
  • That API users can recreate trusted institutional reports independently.

This step is critical for building trust and helping stakeholders understand the parity between internal and external reporting methods.

Permissions and Data Access

The data retrieved through the API is subject to access controls and role-based permissions. In some cases, users may retrieve more or less data through the API compared to the Pure Admin, depending on the API key access definition and visibility into the data.