Versioning coming for $top changes on UAT

Thank you to everyone who has taken the time to evaluate the changes available on our UAT environment

We’re reviewing developer feedback specifically on the $top changes we announced that will bring the Bridge API in line with OData standards and the RESO Web API 2.1.0 Core specification. 

We understand and agree that it’s a significant change to current functionality and, though in line with upcoming industry specifications, introduces a key discrepancy between Bridge and other industry API providers at present. 

To ease the transition, we’re planning to implement versioning on Bridge API endpoints. This will allow data consumers to request the new $top behavior from a new RESO Web API 2.1 endpoint if desired, or continue to pull from the current RESO Web API 2.0 endpoint where the currently-available $top behavior will remain the default for the time being. 

Please anticipate more technical details on this in the coming week. For now, expect that the November 19 production release will not include the $top changes available on UAT. We sincerely appreciate your time and feedback. 

Bridge RESO Web API changes coming; UAT now available for testing

Update 11/8/2024: Please see the updated technical details for this November 19, 2024 release available here.

We’re notifying all Bridge API users in advance of important changes to the API. The UAT environment is available now and data consumers are strongly encouraged to test against it to prepare.

These system-wide changes outlined below will prepare Bridge API MLS datasets for RESO Data Dictionary 2.0 certification. Data consumers can also expect to see several field and enumeration changes to individual datasets over the next several months to bring those datasets better in line with the Data Dictionary 2.0 standard. 

For most of the field name changes between Data Dictionary versions 1.x and 2.0, Bridge API will support both old and new field names simultaneously for the next several months at minimum. However, each data provider (each MLS) may decide whether or not to include those in their outgoing payloads. 

 

What’s changing?

  1. The $top operator will be modified to match the OData specification
    • Bridge API previously treated $top as the page size, whereas OData specifies that $top is meant to be the total collection size. In other words, $top is meant to be the total number of records returned once you have consumed every page. 
    • Clients may specify a given page size by utilizing the maxpagesize header. The current default is 10 with a maximum value of 200.
    • [Update 11/8/2024: In response to developer feedback, we’ll be relocating these $top changes on a new v3 endpoint, to allow data consumers more time & flexibility in converting to the new behavior and to minimize the scope of the changes required for those using the current v2 endpoints. See more information here.]
  2. Our nextLink logic will be modified to allow for replication of any number of records.
  3. $expand queries will now have a default maximum of 10 results, unless otherwise specified with a $top operator within the $expand parameter (e.g., $expand=Listings($top=20)). 
  4. Some resource names will be changing.
    • A correction will be made to the Lookup resource; it is inconsistently reported as Lookups in some places and the plural `s` will be removed.
    • Teams will be renamed to Team.
    • Fields/Resource will be renamed to ResourceName. (This change is specific to the Fields metadata; it already shows correctly as ResourceName in the /Fields payload.)
  5. All requests will now have a default sort order if not otherwise indicated in the request. 
    • Default Sort: ascending 
    • Default OrderBy: BridgeModificationTimestamp (primary), primary key (secondary)

 

When?

These changes will be released into production on November 19, 2024.

There is also a UAT environment with the new format available now, see below.

 

How can I prepare?

Please test against https://uat.bridgedataoutput.com/api/v2/ to confirm that your ingestion processes are compatible before we switch over in production on November 19, 2024.

We encourage you to test against UAT as soon as possible. If you encounter any new behaviors that are inconsistent with the changes listed above, or if you encounter unexpected blockers while integrating with these changes, please contact support@bridgeinteractive.com with “UAT feedback” in the subject line so that our team can review and assist.