Search

RETS Change Proposal 53: Enhancements to Upload Transaction
Author: David Terrell
Organization: Center for REALTORŪ Technology
Telephone:
Address: 430 N. Michigan Ave., Floor 6, Chicago IL, 60611-4087
Email: dterrell@crt.realtors.org
Status: Proposal
Date: 11/07/2003
Proposal Version: 1.7
1. Synopsis
The Update transaction is made safer and easier to reliably parse, also extended to handle binary data (Object upload).
2. Rationale
The update transaction has multiple nested-content key value pairs, which is complex. It is also not capable of supporting binary data (such as image upload), necessitating an otherwise identical transaction
3. Proposal
Update transaction changes

10 Update Transaction
The request format is specified to be multipart/form-data (see rfc 2388), with the following keys:

  • Resource - The ResourceID of the Resource being modified.
  • ClassName - the ClassName of the Class being modified
  • Action - (formerly Validate) one of the following specified actions: Update | Autopop | Validate
  • Type - the UpdateName of the Update being performed
  • Record - See below
  • WarningResponse - See below
  • Object - See below

Record and WarningResponse both have a Content-Type (remember, each key is a separate MIME message part) of text/xml. The format of Record is -


<Record>
 1*(<Field name="SystemName">NewValue</Field>)
</Record>
   

And the format of WarningResponse is

<WarningResponse>
1*(<Response number="warning-num">response</Response>)
</WarningResponse>

   

The WarningResponse value is optional (see RCP 031). If no response is entered for an optional response, an empty element <Response number="warning-num"/> may be used.

The Object key may only be specified for an Add or Modify Update on the Object resource (see RCP 040). This modified transaction eliminates the need for a specialized PostObject transaction, but the Object Resource is needed for this to work.

The response body format remains unchanged.

Alternate solution:

Instead of using multipart/form-data, we could specify a complete XML container format for the Update Transaction request. The Content-Type of the Post would then be XML, and the format would be roughly as follows:

<Update>
 <Resource>resource-id</Resource>
 <Class>class-name</Class>
 <Action> Autopop | Validate | Update </Action>
 <Type> UpdateName </Type>
 <Record> 1* (<Field ... as above />) </Record>
 <WarningResponse> ... contents as above ... </WarningResponse>
</Update>
   

This eliminates the need for multipart parsing for servers that do not support object upload, but makes two separate parse paths based on Content-Type submitted by the client. Image upload would have to use a multipart/form-data content-type with one part called Update with type text/xml and the above XML structure, and the other part being an Object name as specified above.

4. Development Impact
Multipart parsers would need to be incorporated into servers (this is necessary for PostObject anyway), but this is a base part of ASP.NET and a java parser is available from jakarta commons (see File Upload). This makes update data much easier to transmit and parse (the old spec has nested key=value pairs inside the Record= key). It eliminates the need for a separate PostObject transaction. It's also the first time we've actually asked the server to parse XML, but that doesn't seem to be a stretch for RETS.
5. Compatibility
This change is mildly backwards compatible. Servers would be able to distinguish between old-style and new-style requests by looking at the Content-Type (application/x-www-url-encoded for the old style and multipart/form-data or text/xml for the new style).
6. Proof/Need of Concept Examples
None.