Peter Goldey

1. API’s
Successes to Replicate. Pitfalls to Avoid.
2017.01.16
New York
Peter Goldey
pete@witlytic.com

2. Real Estate API’s and me...
Real Estate tech in the 90’s...
pete@witlytic.com
@petergoldey
https://www.linkedin.com/in/p
etergoldey
public records / FOIA
10 Years of API’s @Onboard
2004 - Public Records
2005 - AVM
2008 - IDX Listings
2009 - Geography
2010 - Lifestlye Search
2011 - Area Search
2011 - Boundaries
2011 - Neighborhoods
2011 - Community / Schools
2011 - POI’s
2013 - Transit
2014 - Property API Suite
Founder

3. Things have changed…A LOT!

4. Have a Purpose
Ours was: Delivery Innovation
- recognized by Inman, RISmedia, RE Technology, 1000Watt.
Why did we take a commercial API approach?
- It gave us a vehicle for driving our business forward.
2011 Inman Connect
But we made lots of mistakes…

5. API’s are PRODUCTS
listen to customers, research, marketing, support,
customer feedback, relationship building, use cases,
analytics, stories, value propositions, documentation,
standards, utility, comprehensive testing, platform
management, pricing, security, PR, evangelism,
standards, reuse, stability, experience, purpose

6. API Users vs API Designers
Remember whom you are building for.
Tailor your API accordingly.
Internal?
External?
Developers? What kind?
Who the users are tells you a lot.
what they ask, what type of answers they expect, how they consume it, how often, etc

7. Me in 2004 - API Designer
Good looking
Naive
Knew the domain model REALLY well
Data expert
Designed for:
● Flexibility
● As many use cases as possible
Built it for myself
Assumptions
Over engineered Building our Nearby Home Sales XML service

8. The Awesomeness We Delivered
20+ parameters!
Multivariate interactions!!
Iterative search process!!!
Excellent parameter
documentation.
No restrictions!!
but we missed something big...

9. We didn’t figure out the Right Questions

10. Our Customers in 2005
API user says “Domain what?”
Frustrated
Busy
Lazy
Risk averse
What they wanted:
● Use case solutions
○ Find comps
○ Drip marketing
○ No Dead Ends!
Using our 1st Nearby Home Sales XML service

11. What we did next….
Auto-increment from radius1 and radius2
● Find nearest first. Ensure results.
Added prioritization
● Time vs. Distance
Added priceRangePercent
● Comps based on subject property
Added fuzzy logic for comps
● Best match beds, baths, $, sqft
Listened to clients. Understood their use cases. Made it easy.
Created dateAdded
● Drip marketing trigger
Created geography lookup for updates
● County level lastModified
Created queryID and “requery” method.
● Saved searches method
Added system and per account defaults
● Light weight. Central control.

12. The Results?
Happy clients. (more $$)
“Better” usage. (save $$’s)
Less implementation support. (save $$’s)
Product Management (control)
Happy internal engineers (culture)
New mindset: design for the API user!!!

13. Make is Useful!!
Why will these guys use your API?
They can find it (more on this later).
It offers value (saves time or resources, cost,
features)
It looks “good” (quality, logic, use cases)
Easy to use (version stable*, build for users,
documentation, use features)
* we’re not all like Facebook!!

14. Make it Usable!!
You’re trying to extend your company’s reach.
Find the balance between:
technically sophisticated and simple + concise.
(see DO’s and DON’Ts)

15. Get it out there and ENGAGE!!
...and don’t build everything from scratch!
Leverage API proxy services and communities.

16. Get Listed - API Platforms
My favorite:
16k+ API’s
~150 real estate API’s
Zillow, Trulia, Placester, NYTimes, Onboard, CloudMLS, Retsly, CloudCMA, DotLoop,
StreetEasy, WalkScore, AgentRank, PropertyWala, FlexMLS, SimplyRETS, etc….

17. Make it Look Good!!
Have a Developer Portal
Make Signup Simple
Get to the “value conversation”!!
Have Great Documentation
Twilio, MailChimp, Django, Box
Provide Helpers
samples, SDKs, test tools, libraries
OR

18. Four Takeaways
Your API is a PRODUCT.
Design for the API User.
Simple. Concise. Usable.
Get to the Value Conversation.
pete@witlytic.com
@petergoldey
https://www.linkedin.com/in/petergoldey (keep going for DO’s and DON’Ts)

19. Some DO’s and DON’Ts
* I’m just as biased as the next guy...there are times to break all the rules!
DON’T just expose your domain model…
...DO design for INTENT
DO understand how clients will use the API
DO expose answers to API user’s questions
DON’T require them to be domain experts

20. Some DO’s and DON’Ts
* I’m just as biased as the next guy...there are times to break all the rules!
DON’T use custom when Standards exist!
DO build on HTTP (for quick and easy machine interpretation)
DO build on HTTPS (DON’T pass credentials in the open)

21. Some DO’s and DON’Ts
* I’m just as biased as the next guy...there are times to break all the rules!
DON’T use custom when Standards exist!
DO use RESTful standards - such as naming of resources as nouns
where it makes sense!
DO use RESTful HTTP verbs GET, PUT, POST and DELETE and
respect their qualities.
DON’T abuse GET and POST!!!

22. Some DO’s and DON’Ts
* I’m just as biased as the next guy...there are times to break all the rules!
DON’T use custom when Standards exist!
DO use JSON
DO add XML if you need to (if your API user’s work in Java or C tools, etc.)

23. Some DO’s and DON’Ts
* I’m just as biased as the next guy...there are times to break all the rules!
DON’T use custom when Standards exist!
DON’T limit error codes to 200 and 500
DO use standard error codes (where possible)
DO add to them (where needed and useful)
DO use the right category (200, 300, 400, 500)
DO supply as much detail as possible (e.g. box api)
DO include a requestID

24. Some DO’s and DON’Ts
* I’m just as biased as the next guy...there are times to break all the rules!
DON’T confuse Searching and Identifying!
DO provide multiple ways to search resources (API user intent)
A property as a sale, as a listing, as a location, etc.
DON’T provide multiple ways to identify resources
DO make identity unique
/properties/28199102
DO use redirection and refer to resources by canonical URL

25. Some DO’s and DON’Ts
* I’m just as biased as the next guy...there are times to break all the rules!
DON’T ignore CACHING! (we did - huge mistake)
Caching is going to happen, and it’s a GOOD thing - if you help it.
DO of course be smart with your own internal caching
DO allow your API users to cache results
Fast. Efficient. Inexpensive.
DON’T allow your API users to cache without control!!
Freshness and Visibility concerns

26. Some DO’s and DON’Ts
* I’m just as biased as the next guy...there are times to break all the rules!
DO address “freshness” directly. Make it EASY.
DON’T require API user’s to parse a full response to determine
freshness.
DO use (and respect) Validators
If-Modified-Since in requests
Last-Modified in responses
DO consider using ETags

27. Some DO’s and DON’Ts
* I’m just as biased as the next guy...there are times to break all the rules!
DON’T rely on POLLING! (if you have real estate data, you have
events)
DO bake events into your API
DO create event based resources
DO consider using REST hooks (subscription webhooks) so
developers can receive the latest data without polling.
MAYBE use Long Polling if you really need to.

28. Some DO’s and DON’Ts
* I’m just as biased as the next guy...there are times to break all the rules!
DON’T think only in terms of endpoints!
DON’T make them “search” again.
DO make it easy for API users to find the next resource.
DO use hypermedia controls to provide meaningful links between
resources
DO use canonical urls as resource identifiers
DO use hyperlinks to reference external resources and
information (that’s what they are for!)

29. Some DO’s and DON’Ts
* I’m just as biased as the next guy...there are times to break all the rules!
DO publish a change log. Period.
DO be internally consistent
DO use the same parameter and method names across resources
DON’T use extensions as the only means of content
negotiation / selecting media types
DON’T introduce multiple URL aliases for the same resource
(confusing / ambiguous hypermedia controls)

30. Some DO’s and DON’Ts
* I’m just as biased as the next guy...there are times to break all the rules!
DO NOT use wrapper objects in your responses
They are redundant in a well designed API
DO NOT put metadata in the response body
DO put it where it belongs - in the HTTP response header
there are so many more...