API’s

Successes to Replicate. Pitfalls to Avoid.

2017.01.16New York

Peter Goldeypete@witlytic.com

Real Estate API’s and me...

Real Estate tech in the 90’s...

pete@witlytic.com@petergoldey

https://www.linkedin.com/in/petergoldey

public records / FOIA

10 Years of API’s @Onboard2004 - 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

Things have changed…A LOT!

Have a PurposeOurs 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…

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

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

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 myselfAssumptions

Over engineered Building our Nearby Home Sales XML service

The Awesomeness We Delivered

20+ parameters!

Multivariate interactions!!

Iterative search process!!!

Excellent parameter

documentation.

No restrictions!!

but we missed something big...

We didn’t figure out the Right Questions

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

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.

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!!!

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!!

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)

Get it out there and ENGAGE!!

...and don’t build everything from scratch!

Leverage API proxy services and communities.

Get Listed - API PlatformsMy 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….

Make it Look Good!!

Have a Developer Portal

Make Signup Simple

Get to the “value conversation”!!

Have Great DocumentationTwilio, MailChimp, Django, Box

Provide Helperssamples, SDKs, test tools, libraries

OR

Four Takeaways

Your API is a PRODUCT.

Design for the API User.

Simple. Concise. Usable.

Get to the Value Conversation.

pete@witlytic.com@petergoldeyhttps://www.linkedin.com/in/petergoldey (keep going for DO’s and DON’Ts)

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

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)

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!!!

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.)

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

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

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

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

Allow server logic to determine freshness and act accordingly

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.

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!)

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)

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...