API Integration

API Integration

Overview

VueMotion provides two modes of API integration to enable seamless data exchange for Enterprise and Enterprise+ customers:

1. Push API Integration: VueMotion pushes test data to a user-defined endpoint.

2. Pull API Integration: Customers can pull test data from VueMotion using a secure endpoint.

This guide outlines the processes, formats, and best practices for integrating VueMotion APIs.

Push API Integration

Overview

In Push API Integration, VueMotion sends test data directly to the user's designated endpoint in an agreed-upon JSON format. This method is suited for customers who wish to receive data in real-time or near-real-time.

Process

1. Provide Push API Endpoint

   • The user provides a secure API endpoint for VueMotion to send data.

   • The endpoint must support HTTPS to ensure data security.

2. Agree on JSON Data Format

   • VueMotion will collaborate with the user to define the JSON schema for each test type.

Example JSON schema:
Copy code
{

  "test_id": "12345",

  "athlete_id": "A789",

  "test_type": "Fly-20m",

  "video_id": "345678"

  "upload_timestamp": "1732753245",

  "metrics": {

      "speed": 8.5,

      "acceleration": 3.2,

      "contact_time": 0.45

  }

}

3. Push Sample Data in Staging Environment

   • VueMotion pushes sample test data to the provided endpoint in a staging environment.

   • The user validates the data and confirms compatibility.

4. Move to Production

   • Once validation is complete, the integration moves to the production environment.

   • Real test data is pushed according to the agreed schedule or triggers.

Pull API Integration

Overview

In Pull API Integration, VueMotion provides a unique endpoint for each test, enabling customers to retrieve all relevant test data. API keys and daily usage limits ensure secure and efficient access.

Process

1. API Endpoint Generation

   • VueMotion generates a unique API endpoint for each test type (e.g., /api/v1/tests/acceleration_analysis).

2. API Key Provisioning

   • VueMotion provides the user with an API key to authenticate requests.

     1. Please Note: To get an API key for your account - please contact your VueMotion account manager or send an email to: support@vuemotion.com and we will respond asap.

   • The API key is refreshed every 3 months to enhance security.

3. Daily Usage Limit

   • A pre-negotiated daily usage limit (e.g., 500 requests per day) is applied to the API.

   • Exceeding the limit will result in a 429 Too Many Requests error.

Example API Usage

Endpoint:
GET https://api.vuemotion.com/v1/tests/acceleration_analysis (NOTE: NOT A REAL API endpoint, only a sampler - PLEASE DO NOT USE)

Headers:

http

Copy code

Authorization: Bearer {API_KEY}

Content-Type: application/json

Response Example:

json

Copy code

{

   "test_id": "12345",

   "athlete_id": "A789",

   "test_type": "acceleration_analysis",

   "timestamp": "2024-11-25T14:32:00Z",

   "metrics": {

       "speed": 8.5,

       "acceleration": 3.2,

       "contact_time": 0.45

   }

}

Authentication

Both Push and Pull API integrations require secure handling of data and authentication credentials.

• Push API: The user's endpoint must implement authentication (e.g., Basic Auth, Bearer Tokens, or IP Whitelisting) to ensure data is sent securely.

• Pull API: API keys provided by VueMotion must be included in the Authorization header of each request. Keys are refreshed every 3 months.

Error Handling

Push API

If the user's endpoint is unavailable or returns an error, VueMotion retries the data push up to 3 times with exponential backoff. Persistent failures will trigger a notification to the user.

Pull API

• 401 Unauthorized: Invalid or missing API key.

• 403 Forbidden: The API key does not have access to the requested resource.

• 429 Too Many Requests: Daily usage limit exceeded.

• 500 Internal Server Error: Unexpected error on VueMotion’s side.

Service Availability

API integrations are available exclusively for Enterprise and Enterprise+ customers. Contact your VueMotion account manager for more details.

Support & Contact

For technical assistance, contact the VueMotion support team:
📧 Email: support@vuemotion.com
📞 Phone: +61-405-807-126

We are committed to ensuring a smooth integration process and exceptional service for our customers.