306 lines
8.0 KiB
Markdown
306 lines
8.0 KiB
Markdown
# 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:
|
|
|
|
```python
|
|
# 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)
|
|
|
|
```python
|
|
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:
|
|
|
|
```python
|
|
# 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:
|
|
|
|
```bash
|
|
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
|
|
|
|
```python
|
|
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
|
|
|
|
```python
|
|
# 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.
|