API Evangelist enhancements for PropTrack (REA Group)

overlay: 1.0.0
info:
  title: API Evangelist enhancements for PropTrack (REA Group)
  version: 1.0.0
x-apievangelist:
  generated: '2026-07-27'
  method: generated
  extends_all:
  - openapi/rea-group-address-openapi.yml
  - openapi/rea-group-listings-openapi.yml
  - openapi/rea-group-market-openapi.yml
  - openapi/rea-group-properties-openapi.yml
  - openapi/rea-group-reports-openapi.yml
  - openapi/rea-group-transactions-openapi.yml
  - openapi/rea-group-disclaimers-openapi.yml
  - openapi/rea-group-coming-soon-openapi.yml
  rationale: >-
    PropTrack publishes nine genuine OpenAPI 3.1.0 documents with operationIds,
    summaries, tags, full 4xx/5xx coverage and 189 named response examples - a
    strong contract by catalogue standards. Four things are missing that are
    mechanical to state and that block machine consumption. This overlay records
    them as our enhancement without mutating the harvested originals. Each action
    below corresponds to a finding in review.yml.
actions:
- target: $.components.securitySchemes
  description: >-
    FINDING 1 - No securityScheme is declared in any of the nine documents, even
    though every data operation requires an OAuth 2.0 client-credentials bearer
    token and the provider documents that model in prose at
    /docs/apis/how-to-authenticate. A generated client reads these specs as
    unauthenticated.
  update:
    OAuth2ClientCredentials:
      type: oauth2
      description: >-
        PropTrack partner credentials (api_key / api_secret) exchanged for a JWT
        bearer token with a 3600 second TTL. Client authentication is
        client_secret_basic - credentials must be sent in the Authorization
        header; form parameters are not supported.
      flows:
        clientCredentials:
          tokenUrl: https://data.proptrack.com/oauth2/token
          scopes: {}
- target: $
  description: >-
    Apply the declared scheme globally so every operation inherits it. The OAuth
    token operation itself is the one exception and uses HTTP Basic.
  update:
    security:
    - OAuth2ClientCredentials: []
- target: $.info
  description: >-
    FINDING 2 - info.version is an empty string in all nine documents, so no
    consumer can pin or diff a version. The URI path carries v1/v2 but the
    document does not.
  update:
    x-apievangelist-note: >-
      info.version is empty upstream. Path-level versioning (/api/v1, /api/v2) is
      the only version signal PropTrack publishes.
    contact:
      name: PropTrack Support
      email: support@proptrack.com
      url: https://www.proptrack.com.au/support/contact-support/
- target: $.info
  description: >-
    FINDING 3 - Rate limits, quota behaviour and the cursor pagination contract
    are documented only in prose articles, not in the specs. Surface them as
    extensions so an agent reading the contract alone sees them.
  update:
    x-rate-limits: rate-limits/rea-group-rate-limits.yml
    x-error-catalog: errors/rea-group-error-codes.yml
    x-conventions: conventions/rea-group-conventions.yml
    x-mock-servers: sandbox/rea-group-sandbox.yml
x-findings-not-fixable-by-overlay:
- id: invalid-path-templates
  severity: high
  description: >-
    FINDING 4 - Six path keys in the Properties document are not valid OpenAPI
    path templates. They embed query strings and prose rather than expressing
    requestType as a parameter, e.g.
    "/api/v1/properties/{propertyId}/valuations/sale?requestType=enquiry or
    requestType=origination", "/api/v1/properties/valuations/sale ~ requestType=plus"
    and "/api/v1/properties/valuations/sale ~ Pro". A strict parser will reject or
    mis-route these; codegen produces broken clients. The correct modelling is one
    path with requestType as an enum query parameter. This cannot be repaired by
    an overlay because it changes the path keys themselves - it needs a fix
    upstream.
  affected:
  - openapi/rea-group-properties-openapi.yml
- id: duplicate-operation-ids
  severity: medium
  description: >-
    operationId "listings" is used by both
    GET /api/v2/listings/{listingId} (Listings document) and
    GET /api/v2/properties/{propertyId}/listings (Properties document), and
    "transactions" collides similarly across documents. operationIds are unique
    per document so each file is individually valid, but any tool that merges the
    nine services into one client - which is how the surface is actually consumed
    - gets a collision.
  affected:
  - openapi/rea-group-listings-openapi.yml
  - openapi/rea-group-properties-openapi.yml
- id: non-idiomatic-operation-ids
  severity: low
  description: >-
    Several operationIds are autogenerated slugs
    ("get-api-v2-properties-summaries-search") and one is a raw path
    ("/api/v2/market/demographics"), which is not a usable identifier in generated
    code. Others are clean ("address.match", "market.sale-history"), so the
    convention is inconsistent across the estate.
- id: no-components-reuse
  severity: medium
  description: >-
    components.schemas is empty in all nine documents; every schema is inlined per
    operation. The Properties document is 591KB as a result, and the same logical
    entity (address, attributes) is redefined per operation with no guarantee the
    definitions match. See data-model/rea-group-data-model.yml, which had to
    reconstruct the entity graph from repeated inline shapes.