7. Frequently Asked Questions (FAQ)

General Questions

Q: What is the difference between the REST API and the WebSocket API?

A: The REST API is designed for stateless operations where each request from the client to the server must contain all the information the server needs to fulfill that request. It's suitable for operations that don't require real-time updates.

The WebSocket API, on the other hand, provides a persistent connection allowing for full-duplex communication, making it ideal for real-time data streaming and interactive applications.

Q: How do I obtain my API key?

A: API keys are usually provided during the registration process. If you haven't received your API key, please contact our support team at support@example.com.

Q: What should I do if my API key is not working?

A: Ensure that the API key is correctly included in the Authorization header of your requests. If the issue persists, contact support to verify your API key and permissions.

REST API Questions

Q: How do I authenticate requests to the REST API?

A: First call GET /api/v2/auth/ with your API key in the X-API-Key header. Then include the returned JWT in the Authorization header for protected requests:
```
Authorization: Bearer YOUR_JWT
```

For long-running clients, refresh the JWT with GET /api/v2/auth/refresh/ before its exp time.

Q: What content types does the REST API accept?

A: The REST API accepts JSON-formatted data. Ensure your Content-Type header is set to application/json for all requests that include a body.

Q: How can I test the REST API?

A: You can use tools like curl, Postman, or any HTTP client library in your preferred programming language to test the REST API.

Q: Can I batch multiple requests into one?

A: Currently, the API does not support batching multiple requests into a single call. Each request must be made individually.

WebSocket API Questions

Q: How do I authenticate my WebSocket connection?

A: Obtain a JWT through the REST authentication flow, then pass it in the WebSocket URL:

wss://<robot>/wss?token=YOUR_JWT

A: Send a subscription message in JSON format to the WebSocket server. For example:
```
{
  "subscribe": "telemetry"
}
```

Q: How can I handle reconnections if the WebSocket connection drops?

A: Implement a reconnection strategy in your client application. If the JWT is near expiration, refresh it through /api/v2/auth/refresh/, reconnect with the refreshed token, and re-send your subscriptions. The bundled Wizard frontend and pymirokai client do this automatically.

Q: How do I close the WebSocket connection properly?

A: Send a close frame to the server and then close the connection from the client side. For example:
```
await websocket.close()
```

Q: What message formats are used in the WebSocket API?

A: All messages are in JSON format. Ensure that both the requests you send and the responses you receive are properly formatted JSON objects.

Q: How do I debug WebSocket connection issues?

A: Use WebSocket debugging tools such as browser developer tools or dedicated WebSocket clients to inspect the messages and connection status. Check for correct URL, proper authentication, and valid message formats.

Q: How can I handle errors in the WebSocket API?

A: Listen for error events and handle them appropriately in your client code. Ensure that you implement proper error handling for message parsing errors, connection errors, and subscription errors.