From 515d477aa66917b4308f7073728c28df9ae9fbba Mon Sep 17 00:00:00 2001 From: Alicia Sykes Date: Thu, 25 Sep 2025 19:36:38 +0100 Subject: [PATCH] API --- .github/docs/api.md | 481 ++++ package.json | 3 +- src/lib/components/furniture/Footer.svelte | 2 +- .../components/tools/CIDRDeaggregate.svelte | 188 +- .../components/tools/IPRegexGenerator.svelte | 2 +- .../components/tools/IPv6SolicitedNode.svelte | 10 +- src/lib/components/tools/IPv6Teredo.svelte | 2 +- src/lib/components/tools/NextAvailable.svelte | 1 + src/lib/constants/icon-map.ts | 2 +- src/lib/stores/toolUsage.ts | 2 +- src/lib/utils/api-handler.ts | 71 + src/lib/utils/api-registry.ts | 897 ++++++++ src/lib/utils/cidr-compare.ts | 177 ++ src/lib/utils/cidr-deaggregate.ts | 227 ++ src/lib/utils/dns-tools.ts | 417 ++++ src/routes/api/+server.ts | 37 + src/routes/api/cidr/[tool]/+server.ts | 2 + src/routes/api/dns/[tool]/+server.ts | 2 + .../ip-address-convertor/[tool]/+server.ts | 2 + src/routes/api/subnetting/[tool]/+server.ts | 2 + static/api.html | 22 + static/robots.txt | 2 +- static/sw.js | 8 +- swagger.yaml | 2039 +++++++++++++++++ tests/api/api-overview.test.ts | 51 + tests/api/cidr.test.ts | 390 ++++ tests/api/dns.test.ts | 303 +++ tests/api/ip-address-convertor.test.ts | 269 +++ tests/api/new-endpoints.test.ts | 432 ++++ tests/api/run-api-tests.ts | 16 + tests/api/subnetting.test.ts | 207 ++ tests/api/utils/api-test-helpers.ts | 221 ++ tests/vitest.api.config.ts | 13 + 33 files changed, 6305 insertions(+), 195 deletions(-) create mode 100644 .github/docs/api.md create mode 100644 src/lib/utils/api-handler.ts create mode 100644 src/lib/utils/api-registry.ts create mode 100644 src/lib/utils/cidr-compare.ts create mode 100644 src/lib/utils/cidr-deaggregate.ts create mode 100644 src/lib/utils/dns-tools.ts create mode 100644 src/routes/api/+server.ts create mode 100644 src/routes/api/cidr/[tool]/+server.ts create mode 100644 src/routes/api/dns/[tool]/+server.ts create mode 100644 src/routes/api/ip-address-convertor/[tool]/+server.ts create mode 100644 src/routes/api/subnetting/[tool]/+server.ts create mode 100644 static/api.html create mode 100644 swagger.yaml create mode 100644 tests/api/api-overview.test.ts create mode 100644 tests/api/cidr.test.ts create mode 100644 tests/api/dns.test.ts create mode 100644 tests/api/ip-address-convertor.test.ts create mode 100644 tests/api/new-endpoints.test.ts create mode 100644 tests/api/run-api-tests.ts create mode 100644 tests/api/subnetting.test.ts create mode 100644 tests/api/utils/api-test-helpers.ts create mode 100644 tests/vitest.api.config.ts diff --git a/.github/docs/api.md b/.github/docs/api.md new file mode 100644 index 0000000..157c2c0 --- /dev/null +++ b/.github/docs/api.md @@ -0,0 +1,481 @@ +# API Documentation + +We also got us a REST API. + +It does all the same network calculations and IP address operations as the frontend tools and uses the same logic, but just in a machine-readable way. + +## Base URL + +``` +https://networking-toolbox.as93.net +``` + +The API follows standard HTTP conventions. +And all endpoints accept JSON payloads and return JSON responses. + +## Authentication +None required. The API is completely open. + +## CORS +None required. The API can be called from any origin. Go wild! + +## Response Format + +All responses follow a standard structure: + +```json +{ + "success": true, + "tool": "endpoint-name", + "result": { + // endpoint-specific data + } +} +``` + +Error responses: + +```json +{ + "success": false, + "error": "Error description", + "tool": "endpoint-name" +} +``` + +## Rate Limits +Rate-limiting on the public instance applies after a threshold to prevent abuse (currently, 10 reqs per min and 420 per day).
+But there's a simple work around- just see the Self-Hosting docs! + +## Endpoints + +### Overview + +GET `/api` + +Returns information about all available endpoints. + +### Subnetting + +Calculate detailed subnet information for IPv4 and IPv6 networks. + +
+POST /api/subnetting/ipv4-subnet-calculator + +Calculates comprehensive IPv4 subnet information. + +**Request:** +```json +{ + "cidr": "192.168.1.0/24" +} +``` + +**Response:** +```json +{ + "success": true, + "tool": "ipv4-subnet-calculator", + "result": { + "network": "192.168.1.0", + "broadcast": "192.168.1.255", + "subnetMask": "255.255.255.0", + "wildcardMask": "0.0.0.255", + "prefixLength": 24, + "totalHosts": 256, + "usableHosts": 254, + "firstUsable": "192.168.1.1", + "lastUsable": "192.168.1.254", + "networkClass": "C" + } +} +``` + +
+ +
+POST /api/subnetting/ipv6-subnet-calculator + +Calculates comprehensive IPv6 subnet information. + +**Request:** +```json +{ + "cidr": "2001:db8::/64" +} +``` + +**Response:** +```json +{ + "success": true, + "tool": "ipv6-subnet-calculator", + "result": { + "network": "2001:db8::", + "prefixLength": 64, + "totalAddresses": "18446744073709551616", + "firstAddress": "2001:db8::", + "lastAddress": "2001:db8::ffff:ffff:ffff:ffff", + "expanded": "2001:0db8:0000:0000:0000:0000:0000:0000/64" + } +} +``` + +
+ +### CIDR Operations + +Tools for CIDR notation conversion and manipulation. + +
+POST /api/cidr/cidr-to-subnet-mask + +Converts CIDR prefix to subnet mask. + +**Request:** +```json +{ + "prefix": 24 +} +``` + +**Response:** +```json +{ + "success": true, + "tool": "cidr-to-subnet-mask", + "result": { + "mask": "255.255.255.0" + } +} +``` + +
+ +
+POST /api/cidr/subnet-mask-to-cidr + +Converts subnet mask to CIDR prefix. + +**Request:** +```json +{ + "mask": "255.255.255.0" +} +``` + +**Response:** +```json +{ + "success": true, + "tool": "subnet-mask-to-cidr", + "result": { + "prefix": 24 + } +} +``` + +
+ +
+POST /api/cidr/split + +Split CIDR blocks into smaller subnets. + +**Request (by target prefix):** +```json +{ + "cidr": "192.168.0.0/22", + "targetPrefix": 24 +} +``` + +**Request (by count):** +```json +{ + "cidr": "10.0.0.0/24", + "count": 4 +} +``` + +**Response:** +```json +{ + "success": true, + "tool": "split", + "result": { + "subnets": [ + "192.168.0.0/24", + "192.168.1.0/24", + "192.168.2.0/24", + "192.168.3.0/24" + ], + "totalSubnets": 4, + "originalCidr": "192.168.0.0/22" + } +} +``` + +
+ +
+POST /api/cidr/deaggregate + +Break down CIDR blocks and ranges into uniform subnets. + +**Request:** +```json +{ + "input": "192.168.0.0/22\n10.0.0.0-10.0.0.255\n172.16.1.1", + "targetPrefix": 24 +} +``` + +**Response:** +```json +{ + "success": true, + "tool": "deaggregate", + "result": { + "subnets": [ + "192.168.0.0/24", + "192.168.1.0/24", + "192.168.2.0/24", + "192.168.3.0/24", + "10.0.0.0/24", + "172.16.1.1/32" + ], + "totalSubnets": 6, + "originalBlocks": 3, + "targetPrefix": 24 + } +} +``` + +
+ +
+POST /api/cidr/compare + +Compare two lists of CIDR blocks. + +**Request:** +```json +{ + "listA": "192.168.1.0/24\n10.0.0.0/24\n172.16.0.0/24", + "listB": "192.168.1.0/24\n10.0.1.0/24\n203.0.113.0/24" +} +``` + +**Response:** +```json +{ + "success": true, + "tool": "compare", + "result": { + "added": ["10.0.1.0/24", "203.0.113.0/24"], + "removed": ["10.0.0.0/24", "172.16.0.0/24"], + "unchanged": ["192.168.1.0/24"], + "summary": { + "totalAdded": 2, + "totalRemoved": 2, + "totalUnchanged": 1 + } + } +} +``` + +
+ +### IP Address Tools + +Validation and normalization of IP addresses. + +
+POST /api/ip-address-convertor/validator + +Validate IP addresses and determine their type. + +**Request:** +```json +{ + "ip": "192.168.1.1" +} +``` + +**Response:** +```json +{ + "success": true, + "tool": "validator", + "result": { + "valid": true, + "ipv4": true, + "ipv6": false + } +} +``` + +
+ +
+POST /api/ip-address-convertor/normalize + +Normalize IPv6 addresses to RFC 5952 canonical format. + +**Request:** +```json +{ + "ip": "2001:0db8:0000:0000:0000:0000:0000:0001" +} +``` + +**Response:** +```json +{ + "success": true, + "tool": "normalize", + "result": { + "normalized": "2001:db8::1", + "isValid": true + } +} +``` + +
+ +### DNS Tools + +Generate PTR records and calculate reverse DNS zones. + +
+POST /api/dns/ptr-generator + +Generate PTR records for IP addresses or CIDR blocks. + +**Single IP request:** +```json +{ + "ip": "192.168.1.1" +} +``` + +**CIDR block request:** +```json +{ + "cidr": "192.168.1.0/29", + "template": "server-{octets}.example.com" +} +``` + +**Single IP response:** +```json +{ + "success": true, + "tool": "ptr-generator", + "result": { + "ptr": "1.1.168.192.in-addr.arpa", + "ip": "192.168.1.1" + } +} +``` + +**CIDR block response:** +```json +{ + "success": true, + "tool": "ptr-generator", + "result": { + "records": [ + "0.1.168.192.in-addr.arpa IN PTR server-192-168-1-0.example.com.", + "1.1.168.192.in-addr.arpa IN PTR server-192-168-1-1.example.com." + ], + "template": "server-{octets}.example.com", + "totalRecords": 8 + } +} +``` + +> [!NOTE] +> IPv6 CIDR blocks are only supported for /120 to /128 prefixes due to performance constraints. + +
+ +
+POST /api/dns/reverse-zones + +Calculate required reverse DNS zones for CIDR blocks. + +**Request:** +```json +{ + "cidr": "192.168.1.0/24" +} +``` + +**Response:** +```json +{ + "success": true, + "tool": "reverse-zones", + "result": { + "zones": ["1.168.192.in-addr.arpa"], + "cidr": "192.168.1.0/24", + "ipVersion": 4, + "totalZones": 1 + } +} +``` + +
+ +## Examples + +### Calculate subnet for a /27 network + +```bash +curl -X POST https://networking-toolbox.as93.net/api/subnetting/ipv4-subnet-calculator \ + -H "Content-Type: application/json" \ + -d '{"cidr": "10.0.0.0/27"}' +``` + +### Split a /22 into /24 subnets + +```bash +curl -X POST https://networking-toolbox.as93.net/api/cidr/split \ + -H "Content-Type: application/json" \ + -d '{"cidr": "172.16.0.0/22", "targetPrefix": 24}' +``` + +### Generate PTR records for a subnet + +```bash +curl -X POST https://networking-toolbox.as93.net/api/dns/ptr-generator \ + -H "Content-Type: application/json" \ + -d '{"cidr": "203.0.113.0/29", "template": "host-{index}.example.org"}' +``` + +## Error Handling + +The API returns appropriate HTTP status codes: + +- `200` - Success (even for validation failures) +- `400` - Bad request (invalid parameters) +- `404` - Endpoint not found +- `500` - Internal server error + +Most validation errors return `200` with `success: false` in the response body rather than HTTP error codes. This design choice makes client integration simpler[^1]. + +## Performance Notes + +- CIDR splitting operations with large ranges may take longer +- IPv6 PTR generation is limited to /120-/128 prefixes +- DNS reverse zone calculations are optimized for common subnet sizes + +## OpenAPI Specification + +The complete API specification is available as an [OpenAPI 3.1 document](../../swagger.yaml). + +--- + +[^1]: This follows the "be liberal in what you accept" principle while maintaining consistent response formats. diff --git a/package.json b/package.json index 7d4040c..6ecc092 100644 --- a/package.json +++ b/package.json @@ -1,5 +1,5 @@ { - "name": "ip-calc", + "name": "networking-toolbox", "private": true, "version": "0.2.5", "type": "module", @@ -18,6 +18,7 @@ "test": "vitest", "test:ui": "vitest --ui", "test:coverage": "vitest --coverage", + "test:api": "vitest run --config tests/vitest.api.config.ts", "test:e2e": "playwright test", "test:e2e:ui": "playwright test --ui" }, diff --git a/src/lib/components/furniture/Footer.svelte b/src/lib/components/furniture/Footer.svelte index 2c060a5..a68594c 100644 --- a/src/lib/components/furniture/Footer.svelte +++ b/src/lib/components/furniture/Footer.svelte @@ -7,7 +7,7 @@