APIs - Successes to Replicate. Pitfalls to Avoid.

of 30/30
API’s Successes to Replicate. Pitfalls to Avoid. 2017.01.16 New York Peter Goldey [email protected]
  • date post

    23-Jan-2018
  • Category

    Technology

  • view

    151
  • download

    0

Embed Size (px)

Transcript of APIs - Successes to Replicate. Pitfalls to Avoid.

  1. 1. APIs Successes to Replicate. Pitfalls to Avoid. 2017.01.16 New York Peter Goldey [email protected]
  2. 2. Real Estate APIs and me... Real Estate tech in the 90s... [email protected] @petergoldey https://www.linkedin.com/in/p etergoldey public records / FOIA 10 Years of APIs @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 - POIs 2013 - Transit 2014 - Property API Suite Founder
  3. 3. Things have changedA LOT!
  4. 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. 5. APIs 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. 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. 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. 8. The Awesomeness We Delivered 20+ parameters! Multivariate interactions!! Iterative search process!!! Excellent parameter documentation. No restrictions!! but we missed something big...
  9. 9. We didnt figure out the Right Questions
  10. 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. 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. 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. 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) * were not all like Facebook!!
  14. 14. Make it Usable!! Youre trying to extend your companys reach. Find the balance between: technically sophisticated and simple + concise. (see DOs and DONTs)
  15. 15. Get it out there and ENGAGE!! ...and dont build everything from scratch! Leverage API proxy services and communities.
  16. 16. Get Listed - API Platforms My favorite: 16k+ APIs ~150 real estate APIs Zillow, Trulia, Placester, NYTimes, Onboard, CloudMLS, Retsly, CloudCMA, DotLoop, StreetEasy, WalkScore, AgentRank, PropertyWala, FlexMLS, SimplyRETS, etc.
  17. 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. 18. Four Takeaways Your API is a PRODUCT. Design for the API User. Simple. Concise. Usable. Get to the Value Conversation. [email protected] @petergoldey https://www.linkedin.com/in/petergoldey (keep going for DOs and DONTs)
  19. 19. Some DOs and DONTs * Im just as biased as the next guy...there are times to break all the rules! DONT just expose your domain model ...DO design for INTENT DO understand how clients will use the API DO expose answers to API users questions DONT require them to be domain experts
  20. 20. Some DOs and DONTs * Im just as biased as the next guy...there are times to break all the rules! DONT use custom when Standards exist! DO build on HTTP (for quick and easy machine interpretation) DO build on HTTPS (DONT pass credentials in the open)
  21. 21. Some DOs and DONTs * Im just as biased as the next guy...there are times to break all the rules! DONT 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. DONT abuse GET and POST!!!
  22. 22. Some DOs and DONTs * Im just as biased as the next guy...there are times to break all the rules! DONT use custom when Standards exist! DO use JSON DO add XML if you need to (if your API users work in Java or C tools, etc.)
  23. 23. Some DOs and DONTs * Im just as biased as the next guy...there are times to break all the rules! DONT use custom when Standards exist! DONT 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. 24. Some DOs and DONTs * Im just as biased as the next guy...there are times to break all the rules! DONT 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. DONT provide multiple ways to identify resources DO make identity unique /properties/28199102 DO use redirection and refer to resources by canonical URL
  25. 25. Some DOs and DONTs * Im just as biased as the next guy...there are times to break all the rules! DONT ignore CACHING! (we did - huge mistake) Caching is going to happen, and its 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. DONT allow your API users to cache without control!! Freshness and Visibility concerns
  26. 26. Some DOs and DONTs * Im just as biased as the next guy...there are times to break all the rules! DO address freshness directly. Make it EASY. DONT require API users 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. 27. Some DOs and DONTs * Im just as biased as the next guy...there are times to break all the rules! DONT 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. 28. Some DOs and DONTs * Im just as biased as the next guy...there are times to break all the rules! DONT think only in terms of endpoints! DONT 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 (thats what they are for!)
  29. 29. Some DOs and DONTs * Im 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 DONT use extensions as the only means of content negotiation / selecting media types DONT introduce multiple URL aliases for the same resource (confusing / ambiguous hypermedia controls)
  30. 30. Some DOs and DONTs * Im 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...