API-Referenz

This guide will help you get up and running with the LISA REST API quickly.

Prerequisites#

• HTTP client (curl, Postman, or any programming language HTTP library)
• Valid integrator UID from BioCV
• Basic understanding of REST APIs and JSON

What You'll Learn#

By the end of this guide, you'll know how to:

1. Generate JWT tokens for authentication
2. Make your first API call
3. Understand the response format
4. Use common query parameters

Step 1: Test the API#

First, let's verify the API is working:

# Health check (no authentication required)
curl https://api.biocv.info/api/v1/health

Expected response:

{
  "success": true,
  "message": "LISA REST API is running",
  "timestamp": "2024-12-01T08:47:16.838Z",
  "version": "v1"
}

✅ Great! The API is running. Now let's authenticate.

Step 2: Generate JWT Token#

The LISA API uses JWT token-based authentication. You'll need to generate a token before making API requests.

curl -X POST "https://api.biocv.info/api/v1/tokens" \
  -H "Content-Type: application/json" \
  -d '{
    "integratorUID": "your-integrator-uid",
    "expiresIn": 3600,
    "refreshToken": true
  }'

Response:

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresAt": 1640995200000,
    "tokenType": "Bearer"
  },
  "message": "Token generated successfully",
  "timestamp": "2024-12-01T08:47:16.838Z"
}

Important: Save the accessToken - you'll need it for all API requests.

Step 3: Make Your First API Call#

Now let's use the token to make an authenticated request:

curl -H "Authorization: Bearer your-jwt-token-here" \
     "https://api.biocv.info/api/v1/users/user123/animals"

Replace your-jwt-token-here with the actual access token from the previous step.

Step 4: Understanding the Response#

Your API call will return data in a consistent format:

{
  "success": true,
  "data": [
    {
      "ID": "Cow_001",
      "MAC": "AA:BB:CC:DD:EE:FF",
      "Group": "Barn_A",
      "Sex": "female",
      "Active": true,
      "CurrentTemperature": 38.5,
      "Battery": 85,
      "t": 1701432000000
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 25,
    "totalPages": 3
  },
  "timestamp": "2024-12-01T08:47:16.838Z"
}

Key points:

• success: Always true for successful requests
• data: Contains the actual data (array for lists, object for single items)
• pagination: Shows pagination info for list endpoints
• timestamp: When the response was generated

Step 5: Using Query Parameters#

Most endpoints support query parameters for filtering and pagination:

# Get first 20 animals, sorted by ID
curl -H "Authorization: Bearer your-jwt-token" \
     "https://api.biocv.info/api/v1/users/user123/animals?page=1&limit=20&sortBy=ID&sortOrder=asc"

# Search for animals in a specific group
curl -H "Authorization: Bearer your-jwt-token" \
     "https://api.biocv.info/api/v1/users/user123/animals/search?group=Barn_A"

# Get only active animals
curl -H "Authorization: Bearer your-jwt-token" \
     "https://api.biocv.info/api/v1/users/user123/animals/search?active=true"

Common parameters:

• page - Page number (default: 1)
• limit - Items per page (default: 10, max: 100)
• sortBy - Field to sort by (default: 't' for timestamp)
• sortOrder - Sort order: 'asc' or 'desc' (default: 'desc')

Step 6: Explore Available Data#

The API provides access to several data collections:

• Users - User management and profiles
• Animals - Livestock data and monitoring
• Treatments - Medical treatment records
• Births - Birth event tracking
• LitterGuards - IoT sensor data and analytics
• AI Predictions - Machine learning prediction results

Example: Get LitterGuard Devices#

# Get all LitterGuard devices for a user
curl -H "Authorization: Bearer your-jwt-token" \
     "https://api.biocv.info/api/v1/users/user123/litterguards"

# Get LitterGuard summary statistics
curl -H "Authorization: Bearer your-jwt-token" \
     "https://api.biocv.info/api/v1/users/user123/litterguards/summary"

Example: Get AI Predictions#

# Get all AI predictions for an animal
curl -H "Authorization: Bearer your-jwt-token" \
     "https://api.biocv.info/api/v1/users/user123/animals/AA:BB:CC:DD:EE:FF/predictions"

# Get only heat predictions
curl -H "Authorization: Bearer your-jwt-token" \
     "https://api.biocv.info/api/v1/users/user123/animals/AA:BB:CC:DD:EE:FF/predictions/heat"

What's Next?#

🎉 Congratulations! You've successfully:

• ✅ Tested the API health
• ✅ Generated a JWT token
• ✅ Made your first authenticated API call
• ✅ Understood the response format
• ✅ Used query parameters

Continue Learning#

1. 📖 API Endpoints - Complete endpoint documentation
2. 🔐 Authentication Guide - Detailed authentication info
3. 💡 Code Examples - Implementation examples in various languages
4. ⚡ Best Practices - Optimal API usage guidelines

Getting Help#

• 🔧 Troubleshooting Guide - Common issues and solutions
• ❌ Error Handling Guide - Error codes and responses
• 📧 Contact the LISA Development Team for additional support

Important Notes#

• Rate Limits: 100 requests per 15 minutes per IP
• Security: Always use HTTPS in production
• Tokens: Store JWT tokens securely and implement refresh logic
• Monitoring: Keep track of your API usage