search

samuel-pratt / bc-ferries-api

🛳 The only public API for retrieving current data on BC Ferries sailings.
https://bcferriesapi.ca
MIT License
32 stars 10 forks source link

Master #43

Open pbadams opened 5 months ago

pbadams commented 5 months ago

Overview

This pull request introduces a JSON schema for the BC Ferries API V2. The schema is designed to validate the API response to enhance app data validation, improve consistency across different endpoints, and facilitate easier integration for clients consuming the API.

Schema Details

The schema is structured around two main properties: capacityRoutes and nonCapacityRoutes, each containing an array of route objects. These objects include information such as routeCode, fromTerminalCode, toTerminalCode, sailingDuration, and an array of sailings. Each sailing contains details on the departure time, arrival time, sailing status, fill percentages (overall, cars, and oversize vehicles), and the vessel's name and status.

The schema enforces strict data types and patterns, particularly for time fields (time and arrivalTime), which must match specific time formats or predefined string values indicating non-standard times (e.g., "ETA" or "Variable"). This ensures that clients can reliably parse and display sailing times. The fill, carFill, and oversizeFill fields are numbers between 0 and 100, representing percentage capacities, and are included to aid in capacity planning and visualization.

Use Cases for Unit Testing

  1. Valid Response Parsing: Test cases should verify that API responses matching the schema are correctly parsed and utilized by client applications. This includes handling both capacity and non-capacity routes with varying levels of detail.
  2. Error Handling: Implement tests to ensure that responses not adhering to the schema result in appropriate error handling, such as validation errors being thrown or logged.
  3. Time Format Validation: Specific tests should target the time and arrivalTime fields' pattern matching, including edge cases around 12-hour formats with AM/PM indicators and the handling of special values like "none" or "ETA."
  4. Capacity Calculation: Test the accuracy of capacity calculations in client applications, particularly how they interpret and visualize the fill, carFill, and oversizeFill percentages.