RETS Web API in words we recognize


This post is dedicated to the words used to describe the capabilities found in the RETS Web API published by RESO. Adopting new technologies has challenges with none greater than the vocabulary. I once heard a joke that had a punchline something like

It would not be new technology if the words were familiar!

I am receiving more mail these days regarding the RETS Web API. Most of you already know that the API is NOT a replacement for the RETS processes you use everyday. The API is an other way to access MLS listings. With all approaches to accessing MLS information, you need to be a participant in the MLS first.

Database folks are familiar with term CRUD because is describes the operations supported by databases (CREATE, READ, UPDATE and DELETE). Even if you are not a DBA, the terms are familiar enough to be the basis of understanding the RETS Web API. Let’s look at CRUD as it related to MLS listings:

  • CREATE – Make a new listing
  • READ – Access a listing
  • UPDATE – Change a listing
  • DELETE – OK … obvious … get rid of a listing

Now let’s do this in terms of the RETS Web API. The API is based on the OData Protocol that expresses CRUD operations in terms of HTTP commands. Here is what the map of CRUD to HTTP looks like for the RETS Web API:

  • READ – GET

This is a fairly straight forward translation unless you consider UPDATE. Why would UPDATE be complicated by the three HTTP commands (PUT/PATCH/MERGE). There are two reasons for this. Both reasons move us beyond the CRUD simplification.

First, let’s make a distinction between replacing an entire listing and updating a single field within the listing. In order to replace the entire listing, you would use the PUT command. In order to update a couple of fields, you would use PATCH or MERGE. The second complication has to do with PATCH and MERGE. The original OData Protcol was written with MERGE, but there is no MERGE command in HTTP. As of OData Version 3, PATCH is used instead of MERGE. RESO will follow Odata Version 3, so the translation table now looks like this:

Screen Shot 2014-09-24 at 12.23.52 PM

As a veteran of may RESO meetings, I can only imagine the chaos caused within OData when MERGE was changed to PATCH after two versions of the specification were already released. Changes like this require both courage and a dedication to the industry. Vendors had already deployed MERGE-based products, but the standards group knew that the correct decision was to change to PATCH.

Our industry is just starting to move towards a standardized API. If you look at the OData journey, they started as project Astoria in July 2006. We are starting on a solid foundation of eight years of blood, sweat and tears experienced by others.

Every argument against the RETS Web API has already been made within other industries, years ago. I propose that every argument against the RETS Web API from now on have one of the following preambles:

In the olden days ….

I recall that in the dim and distant past …

And one that many sci-fi fans will like:

A long time ago in a galaxy far, far away …