API's - Successes to Replicate. Pitfalls to Avoid.
Download as PPTX, PDF1 like84 views
The document discusses the evolution of real estate APIs and emphasizes the need to design them with user intent and usability in mind. It highlights important considerations for API development, such as understanding client use cases, using standard practices, and fostering effective communication between the API and its users. Additionally, it provides a series of do's and don’ts to ensure API effectiveness and efficiency.
API's - Successes to Replicate. Pitfalls to Avoid.
- 1. 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
- 2. Things have changed…A LOT!
- 3. 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…
- 4. 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
- 5. 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
- 6. 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
- 7. The Awesomeness We Delivered 20+ parameters! Multivariate interactions!! Iterative search process!!! Excellent parameter documentation. No restrictions!! but we missed something big...
- 8. We didn’t figure out the Right Questions
- 9. 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
- 10. 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.
- 11. 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!!!
- 12. Make it 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!!
- 13. 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)
- 14. Get it out there and ENGAGE!! ...and don’t build everything from scratch! Leverage API proxy services and communities.
- 15. 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….
- 16. 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
- 17. 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)
- 18. 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
- 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 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)
- 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 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!!!
- 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 JSON DO add XML if you need to (if your API user’s work in Java or C tools, etc.)
- 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! 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
- 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 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
- 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 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
- 25. 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
- 26. 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.
- 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 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!)
- 28. 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)
- 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 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...