{"id":20843834,"url":"https://github.com/tkc/go-json-server","last_synced_at":"2025-05-09T01:47:23.292Z","repository":{"id":36625385,"uuid":"156129539","full_name":"tkc/go-json-server","owner":"tkc","description":" golang simple \u0026 quickly JSON mock server","archived":false,"fork":false,"pushed_at":"2025-03-30T01:57:10.000Z","size":2011,"stargazers_count":36,"open_issues_count":0,"forks_count":9,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-05-09T01:47:16.564Z","etag":null,"topics":["go","go-mock-testing","golang","json","json-api","json-server","mock","mock-server","webserver"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tkc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-11-04T22:03:57.000Z","updated_at":"2025-05-05T17:26:16.000Z","dependencies_parsed_at":"2022-08-08T16:15:36.526Z","dependency_job_id":null,"html_url":"https://github.com/tkc/go-json-server","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tkc%2Fgo-json-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tkc%2Fgo-json-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tkc%2Fgo-json-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tkc%2Fgo-json-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tkc","download_url":"https://codeload.github.com/tkc/go-json-server/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253176441,"owners_count":21866142,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["go","go-mock-testing","golang","json","json-api","json-server","mock","mock-server","webserver"],"created_at":"2024-11-18T02:07:30.049Z","updated_at":"2025-05-09T01:47:23.283Z","avatar_url":"https://github.com/tkc.png","language":"Go","readme":"\n![Go](https://github.com/tkc/go-json-server/workflows/Go/badge.svg?branch=master)\n\n```\n  ___          _                 ___                      \n / __|___   _ | |__ _ ___ _ _   / __| ___ _ ___ _____ _ _ \n| (_ / _ \\ | || / _` / _ \\ ' \\  \\__ \\/ -_) '_\\ V / -_) '_|\n \\___\\___/  \\__/\\__,_\\___/_||_| |___/\\___|_|  \\_/\\___|_|  \n                                                          \n```                                                \n\n# Go JSON Server\n\nA powerful, flexible and efficient mock server for testing and development environments. \nServe static JSON APIs and files with customizable routes and responses.\n\n## Requirements\n\n- Go 1.22.3 or later\n\n## Key Features\n\n- ✅ **Configuration-driven API** - Define your endpoints in a simple JSON file\n- ✅ **Hot-reloading** - Changes to configuration are detected and applied without server restart\n- ✅ **Response caching** - Improved performance with configurable TTL\n- ✅ **Path parameters** - Support for dynamic route parameters like `/users/:id`\n- ✅ **Static file server** - Serve files from specified directories\n- ✅ **Middleware architecture** - Logging, CORS, timeout, and panic recovery included\n- ✅ **Structured logging** - Configurable log levels with JSON or text formats\n- ✅ **Request ID tracking** - Assign unique IDs to each request for better traceability\n- ✅ **Error handling** - Detailed error responses and validation\n- ✅ **Command-line flags** - Override configuration settings via command line arguments\n\n## Installation\n\n```bash\n# Install the latest version\ngo install github.com/tkc/go-json-server@latest\n\n# Or using go get \ngo get -u github.com/tkc/go-json-server\n```\n\n## Getting Started\n\n### 1. Create your API configuration file\n\nCreate a file named `api.json` in your project directory:\n\n```json\n{\n  \"port\": 3000,\n  \"logLevel\": \"info\",\n  \"logFormat\": \"text\",\n  \"endpoints\": [\n    {\n      \"method\": \"GET\",\n      \"status\": 200,\n      \"path\": \"/\",\n      \"jsonPath\": \"./health-check.json\"\n    },\n    {\n      \"method\": \"GET\",\n      \"status\": 200,\n      \"path\": \"/users\",\n      \"jsonPath\": \"./users.json\"\n    },\n    {\n      \"method\": \"GET\",\n      \"status\": 200,\n      \"path\": \"/user/:id\",\n      \"jsonPath\": \"./user.json\"\n    },\n    {\n      \"path\": \"/files\",\n      \"folder\": \"./static\"\n    }\n  ]\n}\n```\n\n### 2. Create your JSON response files\n\nCreate the JSON files referenced in your configuration:\n\n**health-check.json**\n```json\n{\n  \"status\": \"ok\",\n  \"message\": \"go-json-server running\",\n  \"version\": \"1.0.0\"\n}\n```\n\n**users.json**\n```json\n[\n  {\n    \"id\": 1,\n    \"name\": \"John Doe\",\n    \"email\": \"john@example.com\"\n  },\n  {\n    \"id\": 2,\n    \"name\": \"Jane Smith\",\n    \"email\": \"jane@example.com\"\n  }\n]\n```\n\n**user.json**\n```json\n{\n  \"id\": \":id\",\n  \"name\": \"John Doe\",\n  \"email\": \"john@example.com\",\n  \"address\": \"123 Main St\"\n}\n```\n\n### 3. Start your server\n\n```bash\ngo-json-server\n```\n\nOr with custom configuration:\n\n```bash\ngo-json-server --config=./custom-config.json --port=8080\n```\n\n## Running, Building and Testing\n\n### Running the Application\n\nYou can run the application directly using Go:\n\n```bash\n# Run from source code\ngo run go-json-server.go\n\n# Run with custom configuration\ngo run go-json-server.go --config=./example/api.json --port=8080 --log-level=debug\n```\n\n### Building the Application\n\nBuild a binary for your current platform:\n\n```bash\n# Simple build\ngo build -o go-json-server\n\n# Build with version information\ngo build -ldflags=\"-X 'main.Version=v1.0.0'\" -o go-json-server\n```\n\nBuild for multiple platforms:\n\n```bash\n# Build for Linux\nGOOS=linux GOARCH=amd64 go build -o go-json-server-linux-amd64\n\n# Build for macOS\nGOOS=darwin GOARCH=amd64 go build -o go-json-server-darwin-amd64\n\n# Build for Windows\nGOOS=windows GOARCH=amd64 go build -o go-json-server-windows-amd64.exe\n```\n\n### Testing\n\nRun all tests:\n\n```bash\n# Run all tests\ngo test ./...\n\n# Run tests with coverage\ngo test -cover ./...\n\n# Run tests with verbose output\ngo test -v ./...\n\n# Run specific package tests\ngo test -v ./src/config\ngo test -v ./src/handler\ngo test -v ./src/logger\ngo test -v ./src/middleware\n```\n\nGenerate and view test coverage:\n\n```bash\n# Generate coverage profile\ngo test -coverprofile=coverage.out ./...\n\n# View coverage in browser\ngo tool cover -html=coverage.out\n\n# Get coverage percentage\ngo tool cover -func=coverage.out\n```\n\nRun benchmark tests:\n\n```bash\n# Run benchmark tests\ngo test -bench=. ./...\n\n# Run benchmark with memory allocation stats\ngo test -bench=. -benchmem ./...\n```\n\n## Configuration Options\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `port` | Server port | 3000 |\n| `host` | Server host | \"\" (all interfaces) |\n| `logLevel` | Logging level (debug, info, warn, error, fatal) | \"info\" |\n| `logFormat` | Log format (text, json) | \"text\" |\n| `logPath` | Path to log file (stdout, stderr, or file path) | \"stdout\" |\n| `endpoints` | Array of endpoint configurations | [] |\n\n### Endpoint Configuration\n\n| Option | Description | Required |\n|--------|-------------|----------|\n| `method` | HTTP method (GET, POST, PUT, DELETE, etc.) | Yes (for API endpoints) |\n| `status` | HTTP response status code | Yes (for API endpoints) |\n| `path` | URL path for the endpoint | Yes |\n| `jsonPath` | Path to JSON response file | Yes (for API endpoints) |\n| `folder` | Path to static files directory | Yes (for file server endpoints) |\n\n## Path Parameters\n\nYou can use path parameters in your routes by prefixing a path segment with a colon:\n\n```json\n{\n  \"method\": \"GET\",\n  \"status\": 200,\n  \"path\": \"/users/:id/posts/:postId\",\n  \"jsonPath\": \"./user-post.json\"\n}\n```\n\nThe parameter values will be available in the JSON response by using the same parameter name with a colon:\n\n```json\n{\n  \"userId\": \":id\",\n  \"postId\": \":postId\",\n  \"title\": \"Sample Post\"\n}\n```\n\n## Command Line Flags\n\n| Flag | Description | Default |\n|------|-------------|---------|\n| `--config` | Path to configuration file | \"./api.json\" |\n| `--port` | Override server port from config | Config port value |\n| `--log-level` | Override log level from config | Config log level |\n| `--log-format` | Override log format from config | Config log format |\n| `--log-path` | Override log path from config | Config log path |\n| `--cache-ttl` | Cache TTL in seconds | 300 (5 minutes) |\n\n## Development Workflow\n\n1. **Clone the repository**:\n   ```bash\n   git clone https://github.com/tkc/go-json-server.git\n   cd go-json-server\n   ```\n\n2. **Install dependencies**:\n   ```bash\n   go mod download\n   ```\n\n3. **Make your changes**:\n   - Add features\n   - Fix bugs\n   - Update documentation\n\n4. **Run tests**:\n   ```bash\n   go test ./...\n   ```\n\n5. **Build and run**:\n   ```bash\n   go build -o go-json-server\n   ./go-json-server --config=./example/api.json\n   ```\n\n## Docker Support\n\nYou can run go-json-server in a Docker container:\n\n```dockerfile\nFROM golang:1.22.3-alpine AS builder\nWORKDIR /app\nCOPY . .\nRUN go build -o /go-json-server\n\nFROM alpine:latest\nWORKDIR /app\nCOPY --from=builder /go-json-server /usr/local/bin/\nCOPY api.json .\nCOPY *.json .\nEXPOSE 3000\nCMD [\"go-json-server\"]\n```\n\nBuild and run with Docker:\n\n```bash\n# Build Docker image\ndocker build -t go-json-server .\n\n# Run Docker container\ndocker run -p 3000:3000 -v $(pwd)/example:/app/example go-json-server --config=/app/example/api.json\n```\n\n## Advanced Examples\n\n### Authentication Middleware Example\n\nTo add basic authentication to your API:\n\n```go\n// In your main.go custom implementation\nauth := func(next http.Handler) http.Handler {\n    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {\n        user, pass, ok := r.BasicAuth()\n        if !ok || user != \"admin\" || pass != \"secret\" {\n            w.Header().Set(\"WWW-Authenticate\", `Basic realm=\"restricted\"`)\n            w.WriteHeader(http.StatusUnauthorized)\n            w.Write([]byte(`{\"error\": \"unauthorized\"}`))\n            return\n        }\n        next.ServeHTTP(w, r)\n    })\n}\n\n// Apply middleware\nhandler := middleware.Chain(\n    middleware.Logger(logger),\n    middleware.CORS(),\n    middleware.Recovery(logger),\n    middleware.RequestID(),\n    auth,\n)(server.HandleRequest)\n```\n\n## Roadmap\n\n- [ ] GraphQL support\n- [ ] WebSocket support\n- [ ] JWT authentication\n- [ ] Response delay simulation\n- [ ] Integration with Swagger/OpenAPI\n- [ ] Proxy mode\n- [ ] Request validation \n- [ ] Response templating\n- [ ] Interactive web UI for API exploration\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## License\n\nMIT ✨\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftkc%2Fgo-json-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftkc%2Fgo-json-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftkc%2Fgo-json-server/lists"}