Inconsistent behaviors re: RESO Web API, ModificationTimestamp, and DaysOnMarket?

[bryanburgers]

I have some questions for the working group related to Web API, ModificationTimestamp, and DaysOnMarket¹.

Imagine this situation.

• On April 21, a listing gets updated in an MLS.
• A consumer of that MLS's public-facing RESO Web API retreives the listing immediately after update.
  • On the payload that is returned, ModificationTimestamp is 2024-04-21T12:46:12Z.
  • On the payload that is returned, DaysOnMarket is 5.
  • On the payload that is returned, StandardStatus is Active.
• The next day, the consumer retrieves the listing again.
  • The selling agent did not make any changes to the listing.
  • On the new payload, ModificationTimestamp is still 2024-04-21T12:46:12Z.
  • On the new payload, StandardStatus is still Active.

The question: on the new payload, what do you expect DaysOnMarket to be?

Before moving on, take a minute to really decide what you think is correct.

(For the visual, here's a diagram of the situation.)

If you answered 5, you're in good company! But if you answered 6, so are you! Currently in the RESO Web API ecosystem, both behaviors can be observed.

Of the RESO Web API Providers I have access to (which isn't all of them) some major providers would return 5 in this case and some major providers would return 6.

It seems Web API Providers fall into two categories (I'm making up terms now): Immutable and Variable.

Immutable

Conceptually, an Immutable provider returns the same content back for a request regardless of when the request was made (immediately after the update occurred or multiple days after the update occured).

Because of this, requests on later days return the same (immutable) payloads.

Immutable diagram

Variable

Conceptually, a Variable provider takes into account when the request was made and returns the most up-to-date data. This describes observable behavior, the actual mechanism here could be calculating DaysOnMarket on the way out or running a script every morning to update the database values.

Because of this, requests on later days return different (variable) payloads.

Variable diagram

The Actual Questions

I am not going to try to enumerate the pros and cons of each approach (I'd love for you, dear reader, to do that below!). Instead, I'm asking these questions:

• Are both of the behaviors valid according to the specification?
• Which is the preferred behavior?
• Do we want to standardize on one or the other? Can we standardize on one or the other?
• Impact is everyone's favorite word in Data Dictionary. At this point in the maturity of the Web API ecosystem, is it even possible to get all providers to use the same behavior? If we decide that one of the two behaviors is specified, are we willing to fail certification for the behavior that isn't?

Footnotes

1. Yes this relates to questions I've received several times about the DaysOnMarket Auto-Increment proposal, but I don't see that proposal as mutually exclusive with whatever comes out of this discussion. ↩