Skip to main content

Developer Quickstart Guide

This guide helps developers quickly integrate with Pidima APIs in the development environment.

Prerequisites​

  • Pidima app running locally on port 22672 (or access to a dev instance)
  • A registered user account
  • An HTTP client (curl, Bruno, Postman, or your preferred tool)

Step 1: Authenticate​

# Login and get your JWT token
TOKEN=$(curl -s -X POST https://staging.example.com/api/v1.0/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "dev@example.com", "password": "your-password"}' \
  | jq -r '.token')

echo $TOKEN

Step 2: List Your Projects​

# Get your account's projects
curl -s https://staging.example.com/api/v1.0/projects/account/{accountId} \
  -H "Authorization: Bearer $TOKEN" | jq

Step 3: Create a Requirement​

curl -X POST https://staging.example.com/api/v1.0/requirements \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "<project-uuid>",
    "name": "REQ-001",
    "title": "System shall authenticate users via SSO",
    "description": "The system shall support SAML 2.0 SSO authentication for enterprise users",
    "priority": "HIGH",
    "type": "FUNCTIONAL",
    "status": "DRAFT"
  }'

Step 4: Generate Test Cases with AI​

curl -X POST https://staging.example.com/api/v1.0/testcases/generate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "requirementId": "<requirement-uuid>",
    "projectId": "<project-uuid>",
    "count": 3
  }'

This returns a job ID for async tracking:

{
  "jobId": "abc-123",
  "status": "PENDING"
}

Step 5: Track Async Job​

curl -s https://staging.example.com/api/v1.0/async-jobs/{jobId} \
  -H "Authorization: Bearer $TOKEN" | jq

Poll until status is COMPLETED.

Step 6: Use AI Chat​

curl -X POST https://staging.example.com/api/v1.0/chat \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What are the safety requirements for the braking system?",
    "projectId": "<project-uuid>"
  }'

Step 7: Export Data​

# Export requirements as Excel
curl -o requirements.xlsx \
  https://staging.example.com/api/v1.0/requirements/download/{projectId}?format=excel \
  -H "Authorization: Bearer $TOKEN"

# Export traceability matrix
curl -o traceability.xlsx \
  https://staging.example.com/api/v1.0/traceability/download/{projectId} \
  -H "Authorization: Bearer $TOKEN"

Common Integration Patterns​

Pattern: Bulk Import Requirements​

# Import from Excel file
curl -X POST https://staging.example.com/api/v1.0/requirements/import/excel \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@requirements.xlsx" \
  -F "projectId=<project-uuid>"
curl -X POST https://staging.example.com/api/v1.0/search \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "emergency braking system failure",
    "projectId": "<project-uuid>",
    "types": ["REQUIREMENT", "TESTCASE"],
    "limit": 10
  }'
curl -X POST https://staging.example.com/api/v1.0/requirement-links \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "requirementId": "<requirement-uuid>",
    "testcaseId": "<testcase-uuid>",
    "projectId": "<project-uuid>",
    "linkType": "VERIFIES"
  }'

Pattern: Impact Analysis After Document Update​

# 1. Upload updated document
curl -X POST https://staging.example.com/api/v1.0/projects/documents \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@updated-spec.pdf" \
  -F "projectId=<project-uuid>"

# 2. Trigger impact analysis
curl -X POST https://staging.example.com/api/v1.0/impact-analysis/trigger \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "<project-uuid>",
    "documentId": "<document-uuid>"
  }'

This project includes a Bruno collection with all API requests pre-configured.

  1. Install Bruno from https://www.usebruno.com/
  2. Open the collection from the pidima-app/bruno/ directory
  3. Set environment variables (baseUrl, token)
  4. Explore and test all endpoints interactively

Bruno is fully offline, stores collections as plain text files (git-friendly), and requires no account.

SDK / Client Libraries​

Currently, no official SDK is provided. We recommend:

  • JavaScript/TypeScript: Use fetch or axios with the Bearer token
  • Python: Use requests library
  • Java: Use Spring's RestTemplate or WebClient

Example: Python Client​

import requests

BASE_URL = "https://staging.example.com/api/v1.0"

# Login
resp = requests.post(f"{BASE_URL}/auth/login", json={
    "email": "dev@example.com",
    "password": "your-password"
})
token = resp.json()["token"]
headers = {"Authorization": f"Bearer {token}"}

# List requirements
requirements = requests.get(
    f"{BASE_URL}/requirements/projects/{project_id}/paginated?page=0&size=20",
    headers=headers
).json()

print(f"Total requirements: {requirements['totalElements']}")
for req in requirements["content"]:
    print(f"  {req['name']}: {req['title']}")

Example: JavaScript/Node.js Client​

const BASE_URL = 'https://staging.example.com/api/v1.0';

// Login
const loginResp = await fetch(`${BASE_URL}/auth/login`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ email: 'dev@example.com', password: 'your-password' })
});
const { token } = await loginResp.json();

// Fetch paginated requirements
const reqResp = await fetch(
  `${BASE_URL}/requirements/projects/${projectId}/paginated?page=0&size=20`,
  { headers: { 'Authorization': `Bearer ${token}` } }
);
const data = await reqResp.json();
console.log(`Total: ${data.totalElements} requirements`);

Environment Configuration​

SettingDev ValueDescription
Base URLhttps://staging.example.comApplication server
DB<db-host>:5432/pidimaPostgreSQL database
Token Expiry24 hoursJWT validity period
Max Upload50MBFile upload limit
AI ProviderconfigurableOllama (local) or cloud LLM

Next Steps​