← Back to Main Documentation

API Documentation

Created: Tue 29 Jul 2025 06:49:39 CEST
Document Version: 1.0 - Initial documentation with timestamp
Security Classification: Public Technical Documentation
Target Audience: Frontend Developers, Backend Developers, API Consumers
Author: Paul Wisén

This directory contains comprehensive API specifications and documentation for the Plings GraphQL system, covering authentication, data models, endpoints, and integration patterns.

Contents

Core API Documentation

• API Endpoints - Complete GraphQL schema and endpoint documentation
• Authentication Flows - JWT authentication, user sessions, and security flows
• Data Models - GraphQL types, object relationships, and data structures
• Error Handling - Error codes, error responses, and troubleshooting

Advanced Features

• Rate Limiting - API rate limits, quotas, and performance considerations
• API Requirements - Technical requirements and integration specifications
• Object Creation Backend Requirements - Specific requirements for object creation APIs

Overview

The Plings API is built on GraphQL to support the complex data relationships and real-time requirements of the Universal Object Graph System. The API enables:

Revolutionary Commerce Integration

• Direct Object Payments: APIs for Solana blockchain integration and HD wallet management
• Service Marketplace: Endpoints for rental, repair, insurance service discovery and booking
• Real-time Ownership: Live updates for blockchain-based ownership transfers
• Payment Processing: Integration with multiple cryptocurrency wallets

Core Object Management

• Object Lifecycle: Create, update, transfer, and manage physical objects
• Relationship Management: Spatial and functional relationships between objects
• Image Management: Multi-image support with main image designation
• Status Tracking: Multi-status object lifecycle management

Advanced Features

• HD Wallet Integration: Cryptographic verification and identifier management
• Multi-tenancy: Organization-based access control with Row Level Security
• Real-time Updates: GraphQL subscriptions for live data synchronization
• Offline Capability: Support for offline object verification and sync

GraphQL Architecture

Why GraphQL Over REST

The complexity of object relationships, real-time commerce features, and mobile optimization requirements make GraphQL the ideal choice:

1. Complex Relationships: Single query for object + relationships + services + payment options
2. Real-time Commerce: Subscriptions for payment status, ownership transfers, location updates
3. Mobile Optimization: Minimize round trips for scanning and payment interfaces
4. Type Safety: Strong typing for financial transactions and blockchain integration

Schema Design Principles

• Commerce-First: Every object is a potential commerce endpoint
• Relationship-Rich: Deep object relationship traversal
• Security-Integrated: JWT authentication with RLS enforcement
• Real-time Capable: Subscription support for live updates

Authentication & Security

Multi-Layer Security

1. JWT Authentication: Supabase-issued tokens with custom claims
2. Row Level Security: PostgreSQL RLS for multi-tenant data isolation
3. GraphQL Authorization: Resolver-level permission checks
4. Rate Limiting: API abuse prevention and performance protection

HD Wallet Security

• Cryptographic Verification: Offline object authenticity validation
• Key Management: Multi-tier HD wallet key security (Vercel → SoftHSM → HSM)
• Payment Security: Program Derived Addresses prevent payment interception

For Frontend Developers

The API enables revolutionary user experiences:

1. Instant Object Details: Rich object information with single GraphQL query
2. Real-time Commerce: Live payment processing and ownership updates
3. Service Discovery: Find available services (rent, repair, insure) for any object
4. Offline Verification: Authenticate objects without network connectivity
5. Wallet Integration: Seamless cryptocurrency payment flows

Key GraphQL Operations

# Object scanning with full commerce context
query ObjectScan($identifier: String!) {
  object(identifier: $identifier) {
    name, owner, currentLocation
    availableServices { type, provider, pricing }
    paymentAddress, verificationStatus
  }
}

# Real-time ownership updates
subscription OwnershipUpdates($objectId: ID!) {
  objectOwnershipChanged(objectId: $objectId) {
    newOwner, transaction, timestamp
  }
}

For Backend Developers

API implementation requires:

1. Dual Database Coordination: Sync between PostgreSQL metadata and Neo4j relationships
2. Blockchain Integration: Solana smart contract interaction and event monitoring
3. Real-time Infrastructure: WebSocket subscriptions and event streaming
4. Security Enforcement: Multi-layer authorization and audit trails
5. Performance Optimization: Efficient graph traversal and caching strategies

Integration Patterns

Commerce Integration

• Payment Processors: Solana wallet adapter integration
• Service Providers: External rental, repair, insurance APIs
• Blockchain Events: Real-time ownership and payment event processing

Business System Integration

• ERP Systems: Inventory and asset management integration
• Identity Providers: SSO and enterprise authentication
• IoT Devices: Sensor data and automated object tracking

Rate Limits & Performance

Standard Rate Limits

• Authenticated Users: 1000 requests/hour
• Anonymous Users: 100 requests/hour
• Real-time Subscriptions: 50 concurrent connections
• Payment Operations: 10 transactions/minute

Performance Considerations

• Graph Queries: Maximum depth of 10 relationship hops
• Batch Operations: Support for bulk object operations
• Caching: Intelligent caching for frequently accessed objects
• CDN Integration: Global content delivery for image assets

Error Handling

GraphQL Error Format

All API errors follow GraphQL standard format with Plings-specific error codes:

{
  "errors": [
    {
      "message": "Object not found or access denied",
      "path": ["object"],
      "extensions": {
        "code": "OBJECT_NOT_FOUND",
        "timestamp": "2025-07-20T10:30:00Z"
      }
    }
  ]
}

Commerce-Specific Errors

• Payment Errors: Blockchain transaction failures and wallet connectivity
• Ownership Errors: Transfer authorization and verification failures
• Service Errors: Provider availability and booking conflicts

API Versioning

Current Version: v1.0

• Versioning Strategy: GraphQL schema evolution with deprecation warnings
• Breaking Changes: 90-day deprecation notice for breaking changes
• Backward Compatibility: Maintain compatibility for critical commerce operations

Getting Started

1. Authentication: Obtain JWT token through Supabase authentication
2. GraphQL Endpoint: https://plings-backend.vercel.app/graphql/ (note trailing slash)
3. Documentation: Use GraphQL introspection for live schema exploration
4. Testing: GraphQL Playground available in development environments

Support & Resources

• API Status: Real-time API status and performance metrics
• Rate Limit Headers: Check remaining quota via response headers
• Error Reporting: Comprehensive error logging for troubleshooting
• Community: Developer forums and integration support