Faker API Service

Mock API that returns fake JSON from schema files. One schema file = one endpoint; folder path = URL path.

Features

• Dynamic endpoint configuration using JSON files
• Support for multiple HTTP methods (GET, POST, PATCH, etc.)
• Nested object and array responses
• Customizable faker patterns
• Input parameter support with placeholders
• GitHub-style documentation UI

Local development

• Prerequisites: Go 1.16+ (or Docker).
• Run (Go): go mod download then go run main.go (or make build && ./microservice). Server: http://localhost:7031.
• Env: Copy .env.example to .env and edit as needed (logging, S3/MinIO; see below).

Docker

1. Clone the repo and go into the project directory:

   
   git clone git@github.com:entrata/faker.git
   cd faker
   

2. Environment: Copy the example env file and set variables (e.g. S3/MinIO, logging):

   
   cp .env.example .env
   

   Edit .env if needed (defaults in .env.example work with the included MinIO setup).
3. Run with Docker Compose (starts app + MinIO; app reads .env and .env.example):

   
   docker compose -f compose.yml up --build
   

   API: http://localhost:7031. MinIO console (if used): port 9001 on the MinIO container.

Schema

• Location: S3 only when S3_BUCKET_NAME is set; otherwise use upload to add schemas (no local assets/schema in this setup).
• Rule: Path = URL. Example: file at key theseus/task.json in S3 → endpoint /theseus/task.
• Format: JSON with description, optional method (GET/POST/PATCH/…), and response (object or array with type, properties or items, and per-field type + faker or enum).
  Fakers: name, email, phone, uuid, street, city, state, zip, number_between (+ params), date|start,end, {{input.key}}|fallback, etc.

Upload (add endpoints)

When S3 is configured, POST /upload adds schema files; folder + filename become the endpoint path.

• Form: endpoint (required) = path prefix; files = one or more .json schema files (multipart).
• URL for each file: /{endpoint}/{filename_without_.json}.

Example (MinIO or S3):

{
  "description": "Comprehensive Example",
  "method": "GET",
  "response": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string",
        "faker": "{{input.id}}|uuid"  // Input parameter with UUID fallback
      },
      "name": {
        "type": "string",
        "faker": "name"  // Random name
      },
      "age": {
        "type": "integer",
        "faker": "{{input.age}}|number_between",  // Input parameter with number range fallback
        "params": [18, 80]
      },
      "email": {
        "type": "string",
        "faker": "email"  // Random email
      },
      "phone": {
        "type": "string",
        "faker": "phone"  // Random phone number
      },
      "status": {
        "type": "string",
        "enum": ["active", "inactive", "pending"]  // Random value from enum
      },
      "score": {
        "type": "number",
        "faker": "number_between",  // Random number in range
        "params": [0, 100]
      },
      "created_at": {
        "type": "string",
        "faker": "date|2020-01-01,2023-12-31,YYYY-MM-DD"  // Random date with format
      },
      "address": {
        "type": "object",
        "properties": {
          "street": {
            "type": "string",
            "faker": "street"  // Random street name
          },
          "city": {
            "type": "string",
            "faker": "city"  // Random city name
          },
          "state": {
            "type": "string",
            "faker": "state"  // Random state name
          },
          "zip": {
            "type": "string",
            "faker": "zip"  // Random zip code
          }
        }
      },
      "tags": {
        "type": "array",
        "faker": "random_element",  // Random array of tags
        "params": [["frontend", "backend", "devops", "qa"]]
      },
      "metadata": {
        "type": "object",
        "properties": {
          "uuid": {
            "type": "string",
            "faker": "uuid"  // Random UUID
          },
          "uuid_digit": {
            "type": "string",
            "faker": "uuid_digit"  // Random numeric UUID
          },
          "sentence": {
            "type": "string",
            "faker": "sentence",  // Random sentence
            "params": [10]  // Number of words
          }
        }
      }
    }
  }
}

Supported Data Types

Type	Description	Example Pattern
string	Basic string value	"faker": "name"
number	Numeric value with range	"faker": "number_between", "params": [0, 100]
uuid	Unique identifier	"faker": "uuid"
uuid_digit	Numeric UUID	"faker": "uuid_digit"
enum	Value from predefined list	"enum": ["active", "inactive", "pending"]
phone	Phone number	"faker": "phone"
email	Email address	"faker": "email"
address	Address components	"faker": "street", "faker": "city", etc.
date	Date with format	"faker": "date|2020-01-01,2023-12-31,YYYY-MM-DD"
array	List of items	"faker": "random_element", "params": [["item1", "item2"]]
object	Nested object structure	See address object example

Input Parameter Support

The API supports input parameters with default values using the format {{input.param}}|default_faker:

{
  "age": {
    "type": "integer",
    "faker": "{{input.age}}|number_between",
    "params": [18, 80]
  }
}

Uploading your schemas

To add or update endpoints, upload your schema JSON files via POST /upload. The server stores them in S3 (or MinIO) and exposes them immediately at URLs derived from the endpoint path and filename.

What you send	What you get
endpoint = path prefix (e.g. client/issues or empty for root)	Base path for all files in this request
files = one or more .json files (multipart)	One API endpoint per file: /{endpoint}/{filename_without_.json}

Example: Upload task.json and tasks.json under the path client/issues. The API will expose: - /client/issues/task (from task.json) - /client/issues/tasks (from tasks.json)

# From the directory that contains task.json and tasks.json:
curl -X POST https://faker.entratadev.green/upload \
  -F "endpoint=client/issues" \
  -F "files=@task.json" \
  -F "files=@tasks.json"

Tips: - Use endpoint= (empty) to put files at the root (e.g. users.json → /users). - Add more -F "files=@other.json" to upload multiple files in one request. - Nested paths like endpoint=api/v1/users create nested URLs (e.g. /api/v1/users/list).

Environment (where uploads go): - Local MinIO: In .env set S3_ENDPOINT=http://minio:9000 (app in Docker), S3_BUCKET_NAME=uploads, and MinIO credentials from compose.yml. - AWS S3: Leave S3_ENDPOINT unset; set S3_BUCKET_NAME, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION.