impulsivefps
/
EU-Utility
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
EU-Utility/docs/NEXUS_DOCUMENTATION_SUMMARY.md

8.0 KiB
Raw Permalink Blame History

Entropia Nexus API Documentation Summary

Summary of completed Nexus API documentation and implementation for EU-Utility

Date: 2025-02-13

Files Created/Updated

Documentation Files Created

File Description Size
docs/NEXUS_LINKTREE.md Complete URL reference for all Nexus endpoints ~7.5 KB
docs/NEXUS_API_REFERENCE.md Full technical API documentation ~18 KB
docs/NEXUS_USAGE_EXAMPLES.md Plugin developer examples ~18 KB

Code Files Updated

File Changes
core/nexus_api.py Added all 25+ entity types, search_by_type(), get_entity_details()
core/plugin_api.py Added nexus_search(), nexus_get_item_details(), nexus_get_market_data()
plugins/base_plugin.py Added convenience methods for plugins to access Nexus API

What's Documented

1. LinkTree (NEXUS_LINKTREE.md)

Complete reference of all Nexus URLs:

  • Base URLs: api.entropianexus.com vs www.entropianexus.com
  • API Endpoints: All 25+ entity endpoints
  • Web Pages: Browseable web interface URLs
  • Entity Type Mapping: API endpoint → web path conversions
  • Query Parameters: All available search/filter parameters
  • Rate Limits: Request limits by endpoint type
  • Response Formats: JSON structure examples

2. API Reference (NEXUS_API_REFERENCE.md)

Complete technical documentation:

  • Authentication: Public API (no auth required)
  • Base Configuration: Rate limits, retry settings, cache TTL
  • Entity Types: All 25+ types documented with descriptions
  • Endpoints:
    • /search - Universal search
    • /{entity-type} - Entity-specific search
    • /items/{id} - Item details
    • /items/{id}/market - Market data
  • Request Parameters: Query options, filters, pagination
  • Response Formats: Complete field documentation for each entity type
  • Error Handling: HTTP codes, exceptions, error responses
  • Rate Limits: Limits per endpoint type
  • Field Name Conventions: Documentation of snake_case vs PascalCase issue
  • Data Classes: Python dataclass reference

3. Usage Examples (NEXUS_USAGE_EXAMPLES.md)

Practical examples for plugin developers:

  • Basic Search: Simple queries with limits
  • Entity-Specific Searches: Weapons, mobs, blueprints, locations, skills
  • Item Details: Full item analysis patterns
  • Market Data: Price checking, monitoring, comparisons
  • Complete Plugin Examples:
    • Weapon Comparator (with DPP calculation)
    • Mob Info lookup
    • Price Checker
  • Advanced Patterns: Caching, batch processing, error handling

Implementation Status

Entity Types Supported

All 25+ entity types are now supported:

Equipment & Items

  • ✅ items - General items
  • ✅ weapons - Weapons
  • ✅ armors - Armors
  • ✅ enhancers - Enhancers

Tools & Professional

  • ✅ medicaltools - Medical tools
  • ✅ finders - Mining finders
  • ✅ excavators - Excavators
  • ✅ refiners - Refiners

Crafting & Materials

  • ✅ blueprints - Blueprints
  • ✅ materials - Materials

Creatures

  • ✅ mobs - Creatures
  • ✅ pets - Pets

Locations

  • ✅ locations - Locations
  • ✅ teleporters - Teleporters
  • ✅ shops - Shops
  • ✅ vendors - Vendors
  • ✅ planets - Planets
  • ✅ areas - Areas

Other

  • ✅ skills - Skills
  • ✅ vehicles - Vehicles
  • ✅ decorations - Decorations
  • ✅ furniture - Furniture
  • ✅ storagecontainers - Storage
  • ✅ strongboxes - Strongboxes

API Methods Available to Plugins

Plugins can now access the Nexus API through:

# In any plugin (extends BasePlugin)
class MyPlugin(BasePlugin):
    def search(self):
        # Search for any entity type
        results = self.nexus_search("ArMatrix", entity_type="weapons")
        
        # Get item details
        details = self.nexus_get_item_details("armatrix_lp-35")
        
        # Get market data
        market = self.nexus_get_market_data("armatrix_lp-35")
        
        # Check API availability
        if self.nexus_is_available():
            # Safe to make calls
            pass

Core API Methods (nexus_api.py)

from core.nexus_api import get_nexus_api

api = get_nexus_api()

# Search methods
api.search_items(query, limit=20)
api.search_mobs(query, limit=20)
api.search_all(query, limit=20)
api.search_by_type(query, entity_type="weapons", limit=20)

# Detail methods
api.get_item_details(item_id)
api.get_entity_details(entity_id, entity_type="mobs")
api.get_market_data(item_id)

# Batch methods
api.get_items_batch([item_id1, item_id2])
api.get_market_batch([item_id1, item_id2])

# Utility
api.clear_cache()
api.is_available()

Known Field Name Conventions

Important: The API returns field names in inconsistent formats:

Concept May Appear As
ID id or Id
Name name or Name
TT Value tt_value, TTValue, TtValue
Damage damage or Damage

Solution: The implementation handles both formats:

# Safe field access
name = item.get('name') or item.get('Name')
tt_value = item.get('tt_value') or item.get('TTValue')

Rate Limits

Endpoint Type Limit
General API 5 req/sec
Search 10 req/min
Market Data 60 req/min
Item Details 30 req/min

Implementation: The client automatically handles:

  • Rate limiting (0.2s between requests)
  • Retry with exponential backoff (max 3 retries)
  • 5-minute default cache for responses

Testing

The implementation includes a test file:

cd projects/EU-Utility
python tests/test_nexus_api.py

Tests verify:

  • Singleton pattern
  • PluginAPI integration
  • All method availability
  • Configuration values

Usage for Plugin Developers

Basic Plugin Template

from plugins.base_plugin import BasePlugin

class MyPlugin(BasePlugin):
    name = "My Plugin"
    version = "1.0.0"
    
    def find_items(self, query):
        # Search Nexus
        results = self.nexus_search(query, entity_type="items")
        return results
    
    def analyze_item(self, item_id):
        # Get full details
        details = self.nexus_get_item_details(item_id)
        market = self.nexus_get_market_data(item_id)
        
        return {
            'item': details,
            'market': market
        }

Entity Type Quick Reference

# Valid entity_type values for nexus_search()
entity_types = [
    "items", "weapons", "armors",
    "mobs", "pets",
    "blueprints", "materials",
    "locations", "teleporters", "shops", "vendors", "planets", "areas",
    "skills",
    "enhancers", "medicaltools", "finders", "excavators", "refiners",
    "vehicles", "decorations", "furniture",
    "storagecontainers", "strongboxes"
]

Related Files

Path Description
core/nexus_api.py Core API client implementation
core/plugin_api.py Plugin API with Nexus integration
plugins/base_plugin.py Base plugin with Nexus convenience methods
plugins/universal_search/plugin.py Real-world usage example
plugins/nexus_search/plugin.py Alternative API client example
tests/test_nexus_api.py Integration tests

Future Enhancements (Noted but Not Implemented)

These are documented but may require API support:

  1. Advanced Filtering: min_level, max_level, planet parameters
  2. Pagination: offset parameter for large result sets
  3. Bulk Endpoints: Batch entity retrieval
  4. Real-time Data: WebSocket support for live market data
  5. User Authentication: If private endpoints become available

Summary

✅ Complete documentation for all Nexus endpoints
✅ 25+ entity types fully supported
✅ Plugin integration via PluginAPI and BasePlugin
✅ Usage examples for common patterns
✅ Error handling and rate limiting implemented
✅ Field name handling for API inconsistencies

The implementation is ready for plugin developers to use the Entropia Nexus API.