Files
wiki-hoist/docs/datahub/reference/overview.md
T
jaime.meza 928a4451f7 Add DataHUB documentation and API reference
- Introduced new documentation for the DataHUB service, including purpose, roles, and business case.
- Added detailed API reference for Quotes and Visits, including search endpoints and response structures.
- Created sections for service records, time reports, and visits in the CustomerHUB documentation.
- Implemented a change log and test plan for the DataHUB project.
- Updated the introduction to include links to the new DataHUB documentation.
- Modified navbar configuration to reflect changes in documentation structure.
2026-11-17 10:42:21 -05:00

33 lines
1.6 KiB
Markdown

---
sidebar_position: 4
title: API Overview & Conventions
---
# DataHUB REST API — Overview & Conventions
Spec and user guide for API consumption. Covers endpoints verified against `hub-dev.hoist.tech` as of 2026-08-04.
**Base URL:** `https://hub-dev.hoist.tech`
**Auth:** header `X-API-KEY: {{apiKey}}` on every request.
---
## API-Wide Conventions
These conventions apply across all DataHUB REST endpoints:
- **Pagination:** `startIndex` (0-based offset) and `maxRecords` (max rows to return). `maxRecords=0` returns the entire matching result set, not zero rows.
- **Identifiers:** each entity uses an `<Entity>Id` field name (e.g. `VisitId`, `QuoteId`).
- **Response envelope:** results are wrapped in an entity-named array, alongside a `TotalCount` reflecting the total matching the filters — independent of `startIndex`/`maxRecords`. The array key name is specific to each endpoint (see its own page).
- **Optional nested data:** arrays/objects added via `include*`-style flags, or that represent related child records, are omitted entirely from the JSON when empty — they are not returned as `[]` or `null`. Client code must use safe/optional field access.
:::warning[Known defect — date filters at/after current time]
Any endpoint accepting a `lastUpdated*`-style datetime filter returns an HTTP 500 (`{"Errors":["Error executing query."],"StatusCode":500}`) when the filter value is at or after the current server time, instead of an empty result set. Root cause unknown — no backend logs available to this team; flagged as an open item.
:::
## Endpoints
- [Quotes/Search](./quotes-search)
- [Visits/Search](./visits-search)