Guides - Shipwrecked API

🔐 Secure API Access with Custom Scopes

Creating Fine-Grained API Keys

curl -X POST "https://api.shipwrecked.co/api-keys" \
     -H "Authorization: Bearer ORG_MASTER_KEY" \
     -H "Content-Type: application/json" \
     -d '{"description": "Analytics reader", "scopes": ["vessels:read", "fuel:forecast"]}'

OAuth 2.0 with Token Refresh

Store tokens securely with automatic refresh:

function refreshAccessToken() {
  const response = fetch("https://api.shipwrecked.co/oauth/token", {
    method: "POST",
    headers: {
      "Content-Type": "application/x-www-form-urlencoded"
    },
    body: `grant_type=refresh_token&refresh_token=${localStorage.getItem("refresh_token")}`
  });
  // Handle response
}

Implement scopes for restricted access:

// Request with limited scope
fetch("https://api.shipwrecked.co/v1/fuel/forecast", {
  headers: {
    "Authorization": `Bearer ${accessToken}`
  }
});

⚙️ Batch Operations and Parallel Requests

Bulk Vessel Creation

curl -X POST "https://api.shipwrecked.co/v1/vessels/batch" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '[{
           "name": "MV Horizon",
           "imo": "1234567"
         }, {
           "name": "MV Pacifica",
           "imo": "7654321"
         }]'

Concurrent API Calls

// JavaScript example
Promise.all([
  fetch("https://api.shipwrecked.co/v1/vessels/12345"),
  fetch("https://api.shipwrecked.co/v1/fuel/forecast?days=7")
])
  .then(responses => Promise.all(responses.map(r => r.json())))
  .then(datas => console.log(datas));

📚 Production Best Practices

Environment Variables

Store secrets securely:

VITE_API_KEY="your-production-key"

Rate Limiting

Handle rate limit headers:

X-RateLimit-Remaining: 2823

Error Budget

Implement error tracking:

errorRate = failedRequests / totalRequests

Developer Guides