Check-Host API

A clean, typed REST API wrapper around Check-Host.net — run ping, HTTP, and TCP availability checks from global monitoring nodes and get back normalized, easy-to-consume JSON.

---

Table of Contents

• About
• Features
• Architecture
• Getting Started
• Configuration
• API Reference
• Typical Workflow
• Project Structure
• Scripts
• Roadmap
• License

---

About

Check-Host.net is a free service that checks the availability and performance of hosts (websites, servers, IPs) from monitoring nodes distributed around the world.

Its public API is powerful but low-level: you fire a check, receive a request_id, then poll a separate endpoint for results that come back as deeply nested, positional arrays. Check-Host API sits in front of it and provides:

• A small, predictable REST surface (/check/*, /node/*).
• Location-based node selection — request checks by country/location code instead of memorizing raw node hostnames.
• Normalized responses — the raw positional arrays returned by Check-Host are mapped into clean, self-describing JSON objects.
• A consistent response envelope (success, message, data, error) for every endpoint.

Features

• ✅ Ping, HTTP, and TCP checks against any host.
• 🌍 Global node discovery with an in-memory cache, grouped by location code.
• 🧭 Select nodes by location (e.g. us, de, ir) rather than raw hostnames.
• 🧹 Response mappers that turn Check-Host's raw output into structured results (latency, status, IP, HTTP status code, etc.).
• 🧱 Layered architecture — routes, controllers, usecases, services, and utilities cleanly separated.
• 🛡️ Centralized error handling and a uniform success/failure envelope.
• 🔤 Fully written in TypeScript with typed domain models.

Architecture

The project follows a layered / clean-architecture style where each request flows through well-defined boundaries:

Route  →  Controller  →  Usecase  →  Service  →  Check-Host.net
                              │
                              └─ maps raw response → normalized JSON

Layer	Responsibility
Routes	Declare HTTP endpoints and bind them to controllers.
Controllers	Parse the request, delegate to a usecase, and shape the HTTP status.
Usecases	Business logic: validate input, resolve nodes, orchestrate services.
Services	Talk to the Check-Host.net HTTP API via a shared Axios client.
Utils	Response envelope, node cache, and raw-to-clean result mappers.

Getting Started

Prerequisites

• Node.js ≥ 18
• npm (or a compatible package manager)

Installation

# Clone the repository
git clone https://github.com/mehdiyahyavi/checkhost-api.git
cd checkhost-api

# Install dependencies
npm install

Running

# Development (hot reload via nodemon + ts-node)
npm run dev

# Production
npm run build   # compiles TypeScript to dist/
npm start       # runs dist/server.js

The server starts on http://localhost:3000 by default.

Configuration

Configuration is read from environment variables (via dotenv). Create a .env file in the project root:

# Port the API server listens on
PORT=3000

# Runtime environment
NODE_ENV=development

Variable	Default	Description
PORT	3000	HTTP port for the API server.
NODE_ENV	development	Runtime environment name.

API Reference

Base URL: http://localhost:3000

All responses share the same envelope:

{
  "success": true,
  "message": "Request success",
  "data": {},
  "error": null
}

Nodes

POST /node/refresh

Fetches the current list of monitoring nodes from Check-Host, groups them by location code, and stores them in the in-memory cache. Run this once before performing checks so that location-based selection works.

curl -X POST http://localhost:3000/node/refresh

GET /node

Returns the cached nodes, grouped by location code.

curl http://localhost:3000/node

{
  "success": true,
  "message": "nodes Found in cache",
  "data": {
    "us": ["us1.node.check-host.net", "us2.node.check-host.net"],
    "de": ["de1.node.check-host.net"]
  }
}

Checks

Each check endpoint accepts the target host and an array of location codes. It returns a request_id that you later exchange for results.

Method	Endpoint	Body
POST	/check/ping	{ "host": string, "location": string[] }
POST	/check/http	{ "host": string, "location": string[] }
POST	/check/tcp	{ "host": string, "location": string[] }

Example — Ping check

curl -X POST http://localhost:3000/check/ping \
  -H "Content-Type: application/json" \
  -d '{ "host": "example.com", "location": ["us", "de"] }'

{
  "success": true,
  "message": "Request success",
  "data": "a1b2c3d4-0000-1111-2222-333344445555"
}

The data field is the request_id. Use it with /check/result.

Results

POST /check/result

Retrieves and normalizes the result of a previously submitted check.

Field	Type	Description
request_id	string	The ID returned by a /check/* endpoint.
type	string	One of ping, http, tcp.

curl -X POST http://localhost:3000/check/result \
  -H "Content-Type: application/json" \
  -d '{ "request_id": "a1b2c3d4-...", "type": "ping" }'

Normalized ping response:

{
  "success": true,
  "message": "Data Success",
  "data": [
    {
      "node": "us1.node.check-host.net",
      "ip": "93.184.216.34",
      "pings": ["0.042", "0.041", "Timeout", "0.043"]
    }
  ]
}

ℹ️ Check-Host runs checks asynchronously. If you request results immediately, some nodes may not have finished yet — poll again after a short delay.

Typical Workflow

sequenceDiagram
    participant Client
    participant API as Check-Host API
    participant CH as Check-Host.net

    Client->>API: POST /node/refresh
    API->>CH: GET /nodes/hosts
    API-->>Client: nodes cached ✔

    Client->>API: POST /check/ping { host, location[] }
    API->>CH: GET /check-ping?host=&node=...
    CH-->>API: request_id
    API-->>Client: request_id

    Client->>API: POST /check/result { request_id, type }
    API->>CH: POST /check-result/{request_id}
    CH-->>API: raw results
    API-->>Client: normalized JSON

Loading

1. Refresh nodes → POST /node/refresh
2. (Optional) List nodes → GET /node
3. Start a check → POST /check/ping | /check/http | /check/tcp → receive request_id
4. Fetch results → POST /check/result with the request_id and type

Project Structure

src/
├── app.ts                       # Express app setup & middleware
├── server.ts                    # HTTP server bootstrap
├── config/
│   ├── config.ts                # Env-based configuration
│   └── host-request-config.ts   # Axios client & Check-Host route map
├── routes/                      # Endpoint definitions
│   ├── index.ts
│   ├── check.routes.ts
│   └── nodes.routes.ts
├── controllers/                 # Request/response handling
│   ├── check.controller.ts
│   └── nodes.controller.ts
├── usecase/                     # Business logic
│   ├── CheckPing.usecase.ts
│   ├── CheckHttp.usecase.ts
│   ├── CheckTcp.usecase.ts
│   ├── Result.usecase.ts
│   └── nodes/
│       ├── fetchNodes.usecase.ts
│       └── getNodes.usecase.ts
├── services/                    # Check-Host.net HTTP calls
│   ├── checks.service.ts
│   ├── check-result.service.ts
│   └── fetchNodes.service.ts
├── util/
│   ├── ApiResponse.ts           # Success/failure envelope
│   ├── nodeCache.ts             # In-memory node cache
│   └── mapper.ts                # Raw → normalized result mappers
├── middlewares/
│   └── errorHandler.ts          # Centralized error handler
└── type/                        # Shared TypeScript types
    ├── GlobalType.ts
    └── NodeTypes.ts

Scripts

Script	Description
npm run dev	Start in watch mode with nodemon + ts-node.
npm run build	Compile TypeScript to dist/.
npm start	Run the compiled server from dist/.
npm run lint	Lint the src/ folder with ESLint.

Roadmap

• DNS check endpoint (/check/dns) — the underlying route already exists in the Check-Host client.
• Persistent node cache / periodic auto-refresh.
• Request validation middleware (e.g. zod).
• Automated tests and CI.
• API documentation via OpenAPI/Swagger.

License

Released under the MIT License. See LICENSE for details.

---

Built with ❤️ using TypeScript & Express — powered by Check-Host.net