Name: UUID Generator API: Fast v1, v4 & Batch ID Generation
Brand: viv-data
SKU: api-viv-data-uuid
Availability: InStock
Author: API Market

gia ly bui

# UUID Generator — v1, v4, Batch Generation

## Overview

The UUID Generator API provides a robust and efficient way to create universally unique identifiers (UUIDs) that conform to RFC 4122. This API supports the generation of both version 1 (time-based) and version 4 (random) UUIDs. Developers can generate single UUIDs or leverage batch generation to produce up to 100 UUIDs in a single request, making it ideal for applications requiring high volumes of unique identifiers across various systems.

## Features

*   **RFC 4122 Compliant:** Generates UUIDs adhering to the official standard.
*   **Version 1 (Time-based) UUIDs:** Create UUIDs based on the current timestamp and MAC address, ensuring uniqueness across space and time.
*   **Version 4 (Random) UUIDs:** Generate cryptographically strong random UUIDs for scenarios where time or location information is not desired.
*   **Single UUID Generation:** Dedicated endpoint for generating one UUID at a time.
*   **Batch Generation:** Efficiently generate up to 100 UUIDs in a single API call, reducing latency and overhead.
*   **Easy Integration:** Simple RESTful interface for straightforward integration into any application.

## Use Cases

1.  **Distributed Database Primary Keys:** Generate unique, collision-resistant primary keys for records in distributed database systems, ensuring data integrity without centralized coordination.
2.  **Session Management & User Tracking:** Create unique session IDs for web applications or track individual user events across multiple services, enhancing analytics and personalization.
3.  **Microservices Communication:** Assign unique request IDs for messages exchanged between microservices, simplifying logging, tracing, and debugging in complex distributed architectures.
4.  **IoT Device Identification:** Provide distinct identifiers for a vast network of Internet of Things (IoT) devices, enabling unique addressing and management of sensor data and device telemetry.
5.  **E-commerce Order & Transaction IDs:** Generate immutable and globally unique identifiers for orders, transactions, or product SKUs, crucial for inventory management, payment processing, and customer support.

## Pricing

*   1 API unit equals 1 request.
*   **Free:** 5,000 req/month
*   **Pro $19.99:** 50,000 req/month
*   Different pricing tiers are available based on usage volume.

## API Documentation

### Base URL

All API requests should be made to: `https://prod.api.market/api/v1/viv-data/uuid`

### Authentication

Authentication is handled via API key. Include your API key in the request header:

```
x-api-market-key: YOUR_API_MARKET_KEY
```

### Endpoints

#### Generate a Single UUID

Generates a single RFC 4122-compliant UUID. By default, it generates a version 4 (random) UUID. You can specify `version=1` for time-based UUIDs.

*   **Path:** `/api/v1/viv-data/uuid/generate`
*   **Method:** `GET`

##### Query Parameters

| Name    | Type    | Description                                                     | Required | Default | Min | Max |
| :------ | :------ | :-------------------------------------------------------------- | :------- | :------ | :-- | :-- |
| `version` | `integer` | The UUID version to generate. `1` for time-based, `4` for random. | No       | `4`     | `1` | `4` |

##### Example Request

```bash
# Generate a default v4 UUID
curl -X GET "https://prod.api.market/api/v1/viv-data/uuid/generate" \
     -H "x-api-market-key: YOUR_API_MARKET_KEY"

# Generate a v1 (time-based) UUID
curl -X GET "https://prod.api.market/api/v1/viv-data/uuid/generate?version=1" \
     -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

##### Example Response (200 OK)

```json
{
  "uuid": "a1b2c3d4-e5f6-4789-0123-456789abcdef",
  "version": 4
}
```

#### Generate Batch UUIDs

Generates multiple RFC 4122-compliant UUIDs in a single request. You can specify the `count` of UUIDs (up to 100) and the `version` (default v4, can be v1).

*   **Path:** `/api/v1/viv-data/uuid/generate-batch`
*   **Method:** `GET`

##### Query Parameters

| Name    | Type    | Description                                                     | Required | Default | Min | Max |
| :------ | :------ | :-------------------------------------------------------------- | :------- | :------ | :-- | :-- |
| `count`   | `integer` | The number of UUIDs to generate in the batch.                   | No       | `10`    | `1` | `100` |
| `version` | `integer` | The UUID version to generate. `1` for time-based, `4` for random. | No       | `4`     | `1` | `4` |

##### Example Request

```bash
# Generate a batch of 5 v4 UUIDs
curl -X GET "https://prod.api.market/api/v1/viv-data/uuid/generate-batch?count=5" \
     -H "x-api-market-key: YOUR_API_MARKET_KEY"

# Generate a batch of 20 v1 UUIDs
curl -X GET "https://prod.api.market/api/v1/viv-data/uuid/generate-batch?count=20&version=1" \
     -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

##### Example Response (200 OK)

```json
[
  {
    "uuid": "a1b2c3d4-e5f6-4789-0123-456789abcdef",
    "version": 4
  },
  {
    "uuid": "b2c3d4e5-f6a7-4890-1234-56789abcdef0",
    "version": 4
  },
  {
    "uuid": "c3d4e5f6-a7b8-4901-2345-6789abcdef01",
    "version": 4
  }
]
```

#### Health Check

Checks the health status of the API service.

*   **Path:** `/api/v1/viv-data/uuid/health`
*   **Method:** `GET`

##### Example Request

```bash
curl -X GET "https://prod.api.market/api/v1/viv-data/uuid/health" \
     -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

##### Example Response (200 OK)

```json
{}
```

## Status Codes

*   **200 OK:** Request successful. The response body contains the requested UUID(s) or an empty object for health checks.
*   **400 Bad Request:** Invalid input parameters or a malformed request. Check the request body and query parameters against the API documentation.
    *   *Example:* Requesting `count=0` or `version=5`.
*   **401 Unauthorized:** Missing or invalid API key. Ensure `x-api-market-key` header is present and contains a valid key.
*   **403 Forbidden:** Valid API key but insufficient permissions to access the requested resource or perform the action.
*   **404 Not Found:** The requested resource or endpoint does not exist. Verify the URL path.
*   **422 Unprocessable Entity:** Validation error due to semantically incorrect request data, even if syntactically correct. Details will be in the response body.
    *   *Example:* Attempting to generate more than 100 UUIDs in a batch request (`count` exceeds maximum).
*   **429 Too Many Requests:** Rate limit exceeded. You have sent too many requests in a given amount of time. Implement backoff and retry logic.
*   **500 Internal Server Error:** A generic error occurred on the server side. This usually indicates an unexpected issue and should be reported if it persists.
*   **503 Service Unavailable:** The service is temporarily unable to handle the request, often due to maintenance or overload. Retry after a short delay.



## Implementation Guide

This section provides code examples to help you quickly integrate the UUID Generator API into your applications. Since this is a synchronous API, examples will show a single request and direct response processing.

### Example Code

Replace `YOUR_API_MARKET_KEY` with your actual API key.

#### JavaScript

```javascript
// JavaScript example for synchronous API calls
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/viv-data/uuid";

async function generateSingleUuid(version = 4) {
  try {
    const response = await fetch(`${baseUrl}/generate?version=${version}`, {
      method: "GET",
      headers: {
        "x-api-market-key": apiKey
      }
    });

    if (!response.ok) {
      const errorData = await response.json();
      throw new Error(`API error: ${response.status} ${response.statusText} - ${JSON.stringify(errorData)}`);
    }

    const uuidResult = await response.json();
    console.log("Generated UUID (Single):", uuidResult);
    return uuidResult;
  } catch (error) {
    console.error("Error generating single UUID:", error);
    throw error;
  }
}

async function generateBatchUuids(count = 10, version = 4) {
  try {
    const response = await fetch(`${baseUrl}/generate-batch?count=${count}&version=${version}`, {
      method: "GET",
      headers: {
        "x-api-market-key": apiKey
      }
    });

    if (!response.ok) {
      const errorData = await response.json();
      throw new Error(`API error: ${response.status} ${response.statusText} - ${JSON.stringify(errorData)}`);
    }

    const uuidResults = await response.json();
    console.log(`Generated UUIDs (Batch of ${count}):`, uuidResults);
    return uuidResults;
  } catch (error) {
    console.error("Error generating batch UUIDs:", error);
    throw error;
  }
}

// Example usage:
(async () => {
  console.log("--- Single UUID Generation ---");
  await generateSingleUuid(); // Default v4
  await generateSingleUuid(1); // v1 time-based

  console.log("\n--- Batch UUID Generation ---");
  await generateBatchUuids(3); // Default 3 v4 UUIDs
  await generateBatchUuids(5, 1); // 5 v1 time-based UUIDs
})();
```

#### Python

```python
# Python example for synchronous API calls
import requests
import json

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/viv-data/uuid"

def generate_single_uuid(version: int = 4):
    """Generates a single UUID."""
    headers = {
        "x-api-market-key": API_KEY
    }
    params = {"version": version}

    try:
        response = requests.get(
            f"{BASE_URL}/generate",
            headers=headers,
            params=params,
            timeout=30 # Recommended timeout for synchronous requests
        )
        response.raise_for_status()  # Raise an exception for HTTP errors (4xx or 5xx)

        uuid_result = response.json()
        print(f"Generated UUID (Single): {json.dumps(uuid_result, indent=2)}")
        return uuid_result
    except requests.exceptions.HTTPError as e:
        print(f"API HTTP error: {e.response.status_code} {e.response.text}")
        raise
    except requests.exceptions.RequestException as e:
        print(f"Request error: {e}")
        raise

def generate_batch_uuids(count: int = 10, version: int = 4):
    """Generates multiple UUIDs in a batch."""
    headers = {
        "x-api-market-key": API_KEY
    }
    params = {"count": count, "version": version}

    try:
        response = requests.get(
            f"{BASE_URL}/generate-batch",
            headers=headers,
            params=params,
            timeout=30 # Recommended timeout for synchronous requests
        )
        response.raise_for_status()  # Raise an exception for HTTP errors (4xx or 5xx)

        uuid_results = response.json()
        print(f"Generated UUIDs (Batch of {count}): {json.dumps(uuid_results, indent=2)}")
        return uuid_results
    except requests.exceptions.HTTPError as e:
        print(f"API HTTP error: {e.response.status_code} {e.response.text}")
        raise
    except requests.exceptions.RequestException as e:
        print(f"Request error: {e}")
        raise

# Example usage:
if __name__ == "__main__":
    print("--- Single UUID Generation ---")
    try:
        generate_single_uuid()  # Default v4
        generate_single_uuid(version=1)  # v1 time-based
    except Exception as e:
        print(f"Failed single UUID generation: {e}")

    print("\n--- Batch UUID Generation ---")
    try:
        generate_batch_uuids(count=3)  # Default 3 v4 UUIDs
        generate_batch_uuids(count=5, version=1)  # 5 v1 time-based UUIDs
    except Exception as e:
        print(f"Failed batch UUID generation: {e}")
```

#### cURL

```bash
# cURL example for synchronous API calls

# Replace YOUR_API_MARKET_KEY with your actual API key

echo "--- Single UUID Generation ---"

# Generate a default v4 UUID
curl -X GET "https://prod.api.market/api/v1/viv-data/uuid/generate" \
     -H "x-api-market-key: YOUR_API_MARKET_KEY"

echo ""

# Generate a v1 (time-based) UUID
curl -X GET "https://prod.api.market/api/v1/viv-data/uuid/generate?version=1" \
     -H "x-api-market-key: YOUR_API_MARKET_KEY"

echo ""

echo "--- Batch UUID Generation ---"

# Generate a batch of 3 v4 UUIDs
curl -X GET "https://prod.api.market/api/v1/viv-data/uuid/generate-batch?count=3" \
     -H "x-api-market-key: YOUR_API_MARKET_KEY"

echo ""

# Generate a batch of 5 v1 UUIDs
curl -X GET "https://prod.api.market/api/v1/viv-data/uuid/generate-batch?count=5&version=1" \
     -H "x-api-market-key: YOUR_API_MARKET_KEY"

echo ""
```

### Performance Optimization

*   **Batch Requests:** For generating multiple UUIDs, always use the `/generate-batch` endpoint instead of making multiple single `/generate` requests. This significantly reduces network overhead and API call count.
*   **Error Handling and Retries:** Implement robust error handling with exponential backoff for transient network errors (`429`, `503`). This prevents unnecessary failed calls and improves your application's resilience.
*   **Caching (if applicable):** While UUIDs are meant to be unique, if your application has a pattern where a specific UUID might be generated and immediately needed elsewhere, consider a short-term cache. However, for most UUID use cases, generation on demand is the standard.
*   **Avoid Unnecessary Calls:** Ensure your application logic only calls the API when a new UUID is genuinely required.

## FAQ

### What is a UUID?

A **Universally Unique Identifier (UUID)** is a 128-bit value used to uniquely identify information in computer systems. When generated according to the UUID standard, UUIDs are considered practically unique across all systems.

---

### What is the difference between UUID v1 and UUID v4?

#### UUID v1 (Time-based)

- Generated using the current timestamp and a MAC address (or a random host identifier).
- Useful when chronological ordering is important.
- May expose information about the generation time and host.

#### UUID v4 (Random)

- Generated using random or pseudo-random numbers.
- Provides excellent collision resistance.
- Does not reveal information about when or where it was generated.
- Recommended for most general-purpose applications.

---

### What is the maximum number of UUIDs I can generate in a batch?

You can generate **up to 100 UUIDs** in a single request using the `/generate-batch` endpoint.

---

### Is there a limit to how many UUIDs I can generate overall?

Yes. API usage is limited by your monthly plan.

For example:

- **Free:** 5,000 requests per month
- **Pro:** 50,000 requests per month

Refer to your pricing plan for the latest usage limits.

---

### How should I handle API errors?

Always check both the HTTP status code and the response body.

Common responses include:

- **`401 Unauthorized`** – Verify that your API key is valid.
- **`422 Unprocessable Entity`** – Check that your request parameters are valid.
- **`429 Too Many Requests`** – Retry using exponential backoff.
- **`503 Service Unavailable`** – Retry after a short delay using exponential backoff.
## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.

Generate RFC 4122-compliant UUIDs quickly. Supports version 1 (time-based) and version 4 (random), with single or batch generation up to 100 IDs.