OpenAPI Specification Improvements

Summary of Changes

This document outlines the errors fixed and optimizations made to the ARS API OpenAPI specifications.

Critical Errors Fixed

1. Regex Pattern Corrections

  • Issue: dispatchId pattern '^[A-Za-z0-9+/]{12}$' required exactly 12 characters, but descriptions stated “12+ character”
  • Fix: Updated pattern to '^[A-Za-z0-9+/]{12,}={0,2}$' to allow 12+ characters and optional base64 padding
  • Files: ars-api.yml, client-api.yml
  • Impact: Prevents validation failures for valid base64 strings longer than 12 characters

2. Typos and Formatting

  • Fixed double spacing in dispatchId description in ars-api.yml
  • Fixed typo: “Disablmement” → “Disablement” in ars-api.yml
  • Removed trailing space in “Hummer “ example in client-api.yml
  • Standardized security array formatting: apiKeyAuth: [ ] → apiKeyAuth: []

3. ETAs Schema Structure

  • Issue: Schema defined as object with additionalProperties, but example showed plain array
  • Fix: Changed to simple array type with items reference
  • File: client-api.yml
  • Impact: Corrects schema/example mismatch

Optimizations Added

4. Validation Constraints

Added comprehensive validation to ensure data quality:

ars-api.yml:

  • dispatchId: minLength: 12, pattern for base64
  • phone: minimum: 1000000000, maximum: 9999999999 (10 digits)
  • year: minimum: 1900, maximum: 2100
  • vin: minLength: 17, maxLength: 17, pattern: '^[A-HJ-NPR-Z0-9]{17}$'
  • odometer: minimum: 0, maximum: 999999
  • zip: pattern: '^\d{5}(-\d{4})?$' (5 or 9 digit format)
  • poNumber: minLength: 1, maxLength: 50
  • etaAgreement: minimum: 1, maximum: 999

client-api.yml:

  • eta: minimum: 1, maximum: 999
  • year: minimum: 1900, maximum: 2100
  • tier: minimum: 1, maximum: 10
  • fileSize: minimum: 1, maximum: 10485760 (10MB limit)
  • dispatchId: minLength: 12

5. Response Schemas

Added proper response content schemas for all POST endpoints:

  • Created SuccessResponse schema for 200 responses
  • Created ErrorResponse schema for 400/403 responses
  • Applied to all endpoints: /requests, /approvals, /cancellations, /goa, /tow, /statuses, /markets

Benefits:

  • Better error handling documentation
  • Improved code generation
  • Consistent API response structure

6. Documentation Updates

  • Added /markets endpoint to README.md endpoint table
  • Updated location.json with proper schema alignment
  • Added deprecation notice to location.json pointing to client-api.yml

7. Schema Alignment

Updated location.json to match the OpenAPI specification:

  • Aligned property names with client-api.yml
  • Added missing validation constraints
  • Marked as legacy with reference to current specification

Impact

These changes improve:

  1. Validation accuracy - Prevents false positives/negatives in API validation
  2. Code generation - Better client/server code generation from OpenAPI specs
  3. API documentation - More complete and accurate API documentation
  4. Data quality - Enforces proper data formats at the schema level
  5. Developer experience - Clearer error messages and expectations

Files Modified

  1. ars-api.yml - ARS server API specification
  2. client-api.yml - Client webhook API specification
  3. README.md - Project documentation
  4. location.json - Legacy location schema (updated and marked deprecated)

Breaking Changes

None. All changes are backwards compatible:

  • Regex patterns are more permissive (allow longer strings)
  • Validation constraints don’t reject previously valid data
  • Response schemas only add structure, don’t change existing behavior

Recommendations

  1. Consider adding more specific HTTP status codes (e.g., 404 for not found, 409 for conflicts)
  2. Add request/response examples to all endpoints
  3. Consider versioning strategy for future API changes
  4. Add rate limiting documentation
  5. Document authentication flow in more detail