feat: scaffold vin-decoder repo — server, data layer, Flux manifests, CI
Closes leeworks-agents/api-company#122 - openapi.yaml: copied from leeworks-agents/api-company apis/vin-decoder/openapi.yaml (canonical spec) - src/db.js: SQLite database init with vin_cache schema and indexes - src/nhtsa.js: NHTSA vPIC fetch + field mapping - src/cache.js: cache read/write with 90-day TTL, validateVin, getCacheStats, evictExpired - src/server.js: Fastify server implementing GET /v1/decode, POST /v1/batch, GET /v1/health - X-RapidAPI-Proxy-Secret middleware on /decode and /batch - X-Request-Id, X-Cache, X-Data-Source response headers - Returns 403 for missing/wrong proxy secret - scripts/seed.js: pre-warm cache with known VINs, runs eviction sweep - src/tests/cache.test.js: unit tests for validateVin + cache integration (Honda Accord VIN) - Dockerfile: Node 20 alpine, non-root, healthcheck on /v1/health - .gitea/workflows/ci.yaml: test → build → push to registry.leeworks.dev/vin-decoder/api:<sha> - flux/vin-decoder/: Namespace, Deployment (with RAPIDAPI_PROXY_SECRET from secret), Service, Ingress (vin.leeworks.dev + TLS), Kustomization - .gitignore: node_modules, data/, .env
This commit is contained in:
agent-company
+405
@@ -0,0 +1,405 @@
|
||||
openapi: 3.1.0
|
||||
info:
|
||||
title: VIN Decoder API
|
||||
version: 1.0.0
|
||||
description: |
|
||||
Decode any 17-character Vehicle Identification Number (VIN) into structured
|
||||
vehicle data including make, model, year, trim, engine, body style, and more.
|
||||
Powered by the NHTSA vPIC public-domain database.
|
||||
|
||||
**Data source:** NHTSA Product Information Catalog and Vehicle Listing (vPIC)
|
||||
public API - US federal government data, public domain (17 U.S.C. 105).
|
||||
|
||||
**Coverage:** Model years 1981-present, all major manufacturers registered
|
||||
with NHTSA (domestic and import).
|
||||
|
||||
**Caching:** Decoded results are cached for 90 days; cache status is
|
||||
indicated by the X-Cache response header.
|
||||
contact:
|
||||
name: leeworks.dev API Support
|
||||
url: https://docs.leeworks.dev
|
||||
license:
|
||||
name: MIT
|
||||
url: https://opensource.org/licenses/MIT
|
||||
|
||||
servers:
|
||||
- url: https://vin.leeworks.dev/v1
|
||||
description: Production
|
||||
|
||||
security:
|
||||
- RapidApiProxy: []
|
||||
|
||||
tags:
|
||||
- name: decode
|
||||
description: VIN decoding endpoints
|
||||
- name: health
|
||||
description: Service health and observability
|
||||
|
||||
paths:
|
||||
/decode:
|
||||
get:
|
||||
operationId: decodeVin
|
||||
summary: Decode a single VIN
|
||||
description: |
|
||||
Decodes a 17-character VIN and returns structured vehicle attributes.
|
||||
Results are cached for 90 days; a cache hit is indicated by
|
||||
X-Cache: HIT in the response headers.
|
||||
tags:
|
||||
- decode
|
||||
parameters:
|
||||
- name: vin
|
||||
in: query
|
||||
required: true
|
||||
description: 17-character Vehicle Identification Number (uppercase, no I/O/Q).
|
||||
schema:
|
||||
type: string
|
||||
minLength: 17
|
||||
maxLength: 17
|
||||
pattern: "^[A-HJ-NPR-Z0-9]{17}$"
|
||||
example: 1HGCM82633A004352
|
||||
- name: raw
|
||||
in: query
|
||||
required: false
|
||||
description: If true, include raw NHTSA vPIC fields in the response.
|
||||
schema:
|
||||
type: boolean
|
||||
default: false
|
||||
responses:
|
||||
"200":
|
||||
description: VIN successfully decoded
|
||||
headers:
|
||||
X-Cache:
|
||||
schema:
|
||||
type: string
|
||||
enum: [HIT, MISS]
|
||||
description: Whether the result was served from cache
|
||||
X-Data-Source:
|
||||
schema:
|
||||
type: string
|
||||
description: Upstream data source identifier
|
||||
X-Request-Id:
|
||||
schema:
|
||||
type: string
|
||||
description: Unique request identifier
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/VinDecodeResult"
|
||||
"400":
|
||||
description: Invalid VIN format or missing parameter
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/Error"
|
||||
"403":
|
||||
description: Missing or invalid RapidAPI proxy secret
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/Error"
|
||||
"429":
|
||||
description: Rate limit exceeded for your plan
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/Error"
|
||||
"500":
|
||||
description: Internal server error or upstream NHTSA API failure
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/Error"
|
||||
|
||||
/batch:
|
||||
post:
|
||||
operationId: decodeVinBatch
|
||||
summary: Decode up to 50 VINs in a single request
|
||||
description: |
|
||||
Accepts a JSON body with an array of VINs (1-50) and returns a decoded
|
||||
result for each. Each VIN is processed independently; partial failures
|
||||
return an error object in that position rather than failing the whole batch.
|
||||
tags:
|
||||
- decode
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
required:
|
||||
- vins
|
||||
properties:
|
||||
vins:
|
||||
type: array
|
||||
minItems: 1
|
||||
maxItems: 50
|
||||
items:
|
||||
type: string
|
||||
minLength: 17
|
||||
maxLength: 17
|
||||
pattern: "^[A-HJ-NPR-Z0-9]{17}$"
|
||||
description: Array of 17-character VINs to decode
|
||||
example:
|
||||
vins:
|
||||
- 1HGCM82633A004352
|
||||
- WBABW33486PX01612
|
||||
responses:
|
||||
"200":
|
||||
description: Batch decode results (one entry per input VIN, in order)
|
||||
headers:
|
||||
X-Request-Id:
|
||||
schema:
|
||||
type: string
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
results:
|
||||
type: array
|
||||
items:
|
||||
oneOf:
|
||||
- $ref: "#/components/schemas/VinDecodeResult"
|
||||
- $ref: "#/components/schemas/VinDecodeError"
|
||||
count:
|
||||
type: integer
|
||||
description: Total number of VINs processed
|
||||
cached_count:
|
||||
type: integer
|
||||
description: Number of results served from cache
|
||||
error_count:
|
||||
type: integer
|
||||
description: Number of VINs that could not be decoded
|
||||
"400":
|
||||
description: Invalid request body
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/Error"
|
||||
"403":
|
||||
description: Missing or invalid RapidAPI proxy secret
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/Error"
|
||||
"429":
|
||||
description: Rate limit exceeded
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/Error"
|
||||
"500":
|
||||
description: Internal server error
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/Error"
|
||||
|
||||
/health:
|
||||
get:
|
||||
operationId: healthCheck
|
||||
summary: Service health check
|
||||
description: |
|
||||
Returns health status of the VIN Decoder service including cache
|
||||
statistics and NHTSA API reachability. Does not require X-RapidAPI-Proxy-Secret.
|
||||
tags:
|
||||
- health
|
||||
security: []
|
||||
responses:
|
||||
"200":
|
||||
description: Service is healthy
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/HealthResponse"
|
||||
"503":
|
||||
description: Service is degraded (upstream unreachable or DB error)
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/HealthResponse"
|
||||
|
||||
components:
|
||||
securitySchemes:
|
||||
RapidApiProxy:
|
||||
type: apiKey
|
||||
in: header
|
||||
name: X-RapidAPI-Proxy-Secret
|
||||
description: |
|
||||
RapidAPI proxy secret injected automatically by RapidAPI on every
|
||||
subscriber request. Direct callers must include this header manually.
|
||||
|
||||
schemas:
|
||||
VinDecodeResult:
|
||||
type: object
|
||||
required:
|
||||
- vin
|
||||
- error_code
|
||||
properties:
|
||||
vin:
|
||||
type: string
|
||||
description: The input VIN (uppercased)
|
||||
example: 1HGCM82633A004352
|
||||
make:
|
||||
type: ["string", "null"]
|
||||
description: Vehicle manufacturer brand
|
||||
example: HONDA
|
||||
model:
|
||||
type: ["string", "null"]
|
||||
description: Vehicle model name
|
||||
example: Accord
|
||||
model_year:
|
||||
type: ["string", "null"]
|
||||
description: Model year as a 4-digit string
|
||||
example: "2003"
|
||||
trim:
|
||||
type: ["string", "null"]
|
||||
description: Trim level (e.g. EX, LX, Sport)
|
||||
example: EX
|
||||
series:
|
||||
type: ["string", "null"]
|
||||
description: Series designation if applicable
|
||||
body_class:
|
||||
type: ["string", "null"]
|
||||
description: Body style classification
|
||||
example: Sedan/Saloon
|
||||
drive_type:
|
||||
type: ["string", "null"]
|
||||
description: Drive configuration
|
||||
example: FWD/Front-Wheel Drive
|
||||
engine_displacement_cc:
|
||||
type: ["number", "null"]
|
||||
description: Engine displacement in cubic centimetres
|
||||
example: 2354
|
||||
engine_displacement_l:
|
||||
type: ["number", "null"]
|
||||
description: Engine displacement in litres
|
||||
example: 2.4
|
||||
engine_cylinders:
|
||||
type: ["integer", "null"]
|
||||
description: Number of engine cylinders
|
||||
example: 4
|
||||
fuel_type_primary:
|
||||
type: ["string", "null"]
|
||||
description: Primary fuel type
|
||||
example: Gasoline
|
||||
transmission_style:
|
||||
type: ["string", "null"]
|
||||
description: Transmission type (Automatic, Manual, CVT, etc.)
|
||||
example: Automatic
|
||||
transmission_speeds:
|
||||
type: ["string", "null"]
|
||||
description: Number of transmission speeds as string
|
||||
example: "5"
|
||||
plant_city:
|
||||
type: ["string", "null"]
|
||||
description: Assembly plant city
|
||||
example: MARYSVILLE
|
||||
plant_state:
|
||||
type: ["string", "null"]
|
||||
description: Assembly plant state/province
|
||||
example: OHIO
|
||||
plant_country:
|
||||
type: ["string", "null"]
|
||||
description: Assembly plant country
|
||||
example: UNITED STATES (USA)
|
||||
manufacturer_name:
|
||||
type: ["string", "null"]
|
||||
description: Full legal name of the manufacturer
|
||||
example: HONDA OF AMERICA MFG., INC.
|
||||
vehicle_type:
|
||||
type: ["string", "null"]
|
||||
description: NHTSA vehicle type classification
|
||||
example: PASSENGER CAR
|
||||
error_code:
|
||||
type: string
|
||||
description: NHTSA decode error code. "0" means successful decode.
|
||||
example: "0"
|
||||
error_text:
|
||||
type: ["string", "null"]
|
||||
description: Human-readable decode error (null when error_code is "0")
|
||||
cached:
|
||||
type: boolean
|
||||
description: Whether this result was served from the local cache
|
||||
example: true
|
||||
|
||||
VinDecodeError:
|
||||
type: object
|
||||
required:
|
||||
- vin
|
||||
- error
|
||||
- message
|
||||
properties:
|
||||
vin:
|
||||
type: string
|
||||
description: The VIN that could not be decoded
|
||||
error:
|
||||
type: string
|
||||
description: Error code
|
||||
example: INVALID_VIN
|
||||
message:
|
||||
type: string
|
||||
description: Human-readable error description
|
||||
example: VIN must be exactly 17 alphanumeric characters
|
||||
|
||||
Error:
|
||||
type: object
|
||||
required:
|
||||
- error
|
||||
- message
|
||||
- status
|
||||
properties:
|
||||
error:
|
||||
type: string
|
||||
description: Machine-readable error code
|
||||
example: BAD_REQUEST
|
||||
message:
|
||||
type: string
|
||||
description: Human-readable error description
|
||||
example: "Query parameter 'vin' is required"
|
||||
status:
|
||||
type: integer
|
||||
description: HTTP status code
|
||||
example: 400
|
||||
|
||||
HealthResponse:
|
||||
type: object
|
||||
required:
|
||||
- status
|
||||
- version
|
||||
properties:
|
||||
status:
|
||||
type: string
|
||||
enum: [ok, degraded]
|
||||
description: Overall service health
|
||||
version:
|
||||
type: string
|
||||
description: Service version
|
||||
example: "1.0.0"
|
||||
uptime_seconds:
|
||||
type: integer
|
||||
description: Seconds since the service started
|
||||
example: 86400
|
||||
cache:
|
||||
type: object
|
||||
properties:
|
||||
entries:
|
||||
type: integer
|
||||
description: Number of cached VIN records
|
||||
hit_rate_24h:
|
||||
type: number
|
||||
description: Cache hit rate over the last 24 hours (0.0-1.0)
|
||||
size_mb:
|
||||
type: number
|
||||
description: SQLite cache file size in megabytes
|
||||
upstream:
|
||||
type: object
|
||||
properties:
|
||||
nhtsa_vpic:
|
||||
type: string
|
||||
enum: [reachable, unreachable]
|
||||
description: NHTSA vPIC API reachability
|
||||
last_check:
|
||||
type: string
|
||||
format: date-time
|
||||
description: ISO-8601 timestamp of last upstream health check
|
||||
Reference in New Issue
Block a user