tilbudgivern/docs/archived/apitest/FILE_GUIDE.md

# File Guide - Ordrestyring GraphQL API Test Suite

Quick reference for all files in this project.

## 📖 Start Here

| File | Purpose | Size | Read Time |
|------|---------|------|-----------|
| **INDEX.md** | Project overview & quick start | Medium | 3 min |
| **README_API.md** | Complete API documentation | Large | 15 min |
| **TESTING_SUMMARY.md** | Test report & learnings | Medium | 5 min |
| **FILE_GUIDE.md** | This file - navigation guide | Small | 2 min |

## 🔑 Configuration Files

| File | Purpose | Security |
|------|---------|----------|
| `apikey` | API authentication token | 🔒 SECRET - **DO NOT COMMIT** |
| `apikey.example` | Example template for apikey | Safe to commit |
| `apiendpoint` | Production API endpoint URL | Public |

**⚠️ SECURITY WARNING:** The `apikey` file contains sensitive credentials and must NEVER be committed to version control. Use `apikey.example` as a template to create your local `apikey` file.

## 🔧 Test Scripts (18 files)

All scripts located in `examples/` directory:

### Read Operations (17 scripts)
| Script | Endpoint | Description |
|--------|----------|-------------|
| `curl_cases.sh` | cases | List all cases with pagination |
| `curl_case_by_id.sh` | caseById | Get specific case (requires ID param) |
| `curl_offers.sh` | offers | List all offers with pagination |
| `curl_offer_by_id.sh` | offer | Get specific offer by ID |
| `curl_customers.sh` | customers | List all customers with pagination |
| `curl_customer_by_id.sh` | customer | Get specific customer by ID |
| `curl_products.sh` | products | List all products with pagination |
| `curl_users.sh` | users | List all users with pagination |
| `curl_departments.sh` | departments | List all departments |
| `curl_installations.sh` | installations | List all installations |
| `curl_services.sh` | services | List all service agreements |
| `curl_todos.sh` | todos | List all todos |
| `curl_events.sh` | events | List calendar events (requires between param) |
| `curl_sales_invoices.sh` | salesInvoices | List sales invoices |
| `curl_creditor_invoices.sh` | creditorInvoices | List creditor invoices |
| `curl_hours.sh` | hours | List time registrations |
| `curl_invoices.sh` | invoices | List all invoices |

### Write Operations (2 scripts) ⚠️
| Script | Endpoint | Description | Cleanup |
|--------|----------|-------------|---------|
| `curl_create_offer.sh` | createOffer | Create new offer | Includes delete |
| `curl_upload.sh` | uploadCaseDocument | Upload document to case | Includes delete |

## 💾 Output Files (18 files)

All outputs in `examples/output/` directory:

Each test script has a corresponding `.output.json` file:
- Format: `curl_<endpoint>.sh.output.json`
- Content: Actual API responses from production
- Usage: Reference for expected responses and data structure

Example:
```bash
examples/output/curl_cases.sh.output.json       # Response from cases query
examples/output/curl_users.sh.output.json       # Response from users query
```

## 📋 Inventory & Documentation

| File | Format | Purpose |
|------|--------|---------|
| `examples/endpoint_inventory.json` | JSON | Structured list of all 19 endpoints |
| `examples/endpoint_inventory.csv` | CSV | Same data, spreadsheet friendly |
| `examples/rollback_plan.md` | Markdown | Cleanup procedures for write ops |
| `examples/python_client.py` | Python | Example Python implementation |

## 🗂️ Directory Structure

```
/home/w34078/scripts/apitest/
├── INDEX.md                           # 👈 Start here!
├── README_API.md                      # Main documentation
├── TESTING_SUMMARY.md                 # Test report
├── FILE_GUIDE.md                      # This file
├── apikey                             # 🔒 API key (secret)
├── apiendpoint                        # Endpoint URL
├── test_graphql.sh                    # Legacy test script
│
└── examples/
    ├── endpoint_inventory.json        # Endpoint list (JSON)
    ├── endpoint_inventory.csv         # Endpoint list (CSV)
    ├── rollback_plan.md               # Cleanup docs
    ├── python_client.py               # Python example
    │
    ├── curl_*.sh                      # 18 test scripts
    │
    └── output/
        └── curl_*.sh.output.json      # 18 response files
```

## 🎯 Common Tasks

### Read Documentation
```bash
# Overview and quick start
cat INDEX.md

# Complete API documentation
cat README_API.md

# Test findings and learnings
cat TESTING_SUMMARY.md
```

### Run Tests
```bash
# Simple query
bash examples/curl_cases.sh

# Query with parameter
bash examples/curl_case_by_id.sh 8806

# View output
cat examples/output/curl_cases.sh.output.json | jq .
```

### Check Status
```bash
# Count all scripts
ls -1 examples/curl_*.sh | wc -l

# Count all outputs
ls -1 examples/output/*.json | wc -l

# Verify all outputs are valid
for f in examples/output/*.json; do
  if jq empty "$f" 2>/dev/null; then
    echo "✅ $(basename $f)"
  else
    echo "❌ $(basename $f)"
  fi
done
```

### Explore API
```bash
# Use GraphiQL explorer
# Visit: https://graphql.ordrestyring.dk/graphiql

# Or introspect via curl
API_KEY=$(cat apikey)
curl -X POST https://graphql.ordrestyring.dk/graphql \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"query":"{ __schema { types { name } } }"}'
```

## 📊 File Statistics

- **Total files:** 50+
- **Documentation:** 5 files
- **Test scripts:** 18 files
- **Output files:** 18 files
- **Configuration:** 2 files
- **Inventory:** 4 files (JSON, CSV, MD, Python)

## 🔍 Finding Things

### By Purpose
- **Learning:** Start with INDEX.md, then README_API.md
- **Testing:** Use scripts in examples/
- **Reference:** Check outputs in examples/output/
- **Integration:** Use python_client.py as template

### By Type
- **Queries (read):** 17 endpoints tested
- **Mutations (write):** 2 endpoints tested (with cleanup)
- **Special:** events endpoint requires `between` parameter

## ⚠️ Important Notes

1. **API Key:** The `apikey` file contains sensitive credentials and must NEVER be committed to version control. Use `apikey.example` as a template to create your local `apikey` file.
2. **Production:** All tests run against production, be careful with writes
3. **Cleanup:** Write operations include cleanup steps
4. **Outputs:** Contain real data, may include sensitive information
5. **Updates:** Re-run scripts to get fresh data

## 📅 Maintenance

When updating:
1. Run script to test endpoint
2. Save output to examples/output/
3. Update endpoint_inventory.json
4. Update README_API.md with new example
5. Update TESTING_SUMMARY.md
6. Update this FILE_GUIDE.md if needed

---

**Last updated:** 2025-10-23  
**Total endpoints documented:** 19  
**Test coverage:** 100%