Applied APIs

API Recommended Practice 1160

Managing System Integrity for Hazardous Liquid Pipelines

The boring part

The guy standing and talking: Patrick Heneise, @PatrickHeneise

"Full Stack JavaScript Architect with a focus on mobile"

Mobile Architect

#nodejs #nosql #couchbase #couchdb #redis #elasticsearch #api #iphone #android #firefoxos #phonegap #cordova

• MSc Media Technology, Universiteit Leiden, 2011
• BSc Computer Science in Media, Furtwangen University, 2010
• some other titles nobody cares about.

Why I'm standing here?

Because I care about APIs.

Topics

1. Security & Authentication
2. API Methodologies
3. Tracking & Analytics
4. Error Handling
5. Summary

Security & Authentication

Different types of authentication:

• OAuth2
• OAuth2
• OAuth2

But OAuth2 is so complicated. Can I use ...

Implement OAuth2 right from the start, don't try to use anything else. You'll end up with it sooner or later anyway.*

* Until something else comes out.

API Methodologies

• Pulling API (REST)
• Pushing API
• Realtime API

'Pulling' REST API

REST: The good

• open access to your data
• access/provide large amounts of data
• filter and search for data
• operations (POST, DELETE ...)

REST: The bad

• client needs to request data
• no updates
• no realtime

Example: Tumblr

			Request: http://api.tumblr.com/v2/tagged?tag=gif
			Response: {
  "meta":{
    "status":200,
    "msg":"OK"},
    "response":[]
}
		

Don'ts: Tumblr

			"\u003C\/p\u003E\n\u003Cp\u003ECopa del Rey\u00a0"
		

Never return nonsense.

Pushing API

Push: The good

• updates when required
• best use of data
• almost realtime

Push: The bad

• no filters
• no searches

Example: Instagram

curl -F 'client_id=CLIENT-ID' \
	-F 'client_secret=CLIENT-SECRET' \
	-F 'object=tag' \
	-F 'aspect=media' \
	-F 'object_id=nofilter' \
	-F 'callback_url=http://YOUR-CALLBACK/URL' \
	https://api.instagram.com/v1/subscriptions/
		

Don'ts: Instagram

			{
  "subscription_id": "1",
  "object": "user",
  "object_id": "1234",
  "changed_aspect": "media",
  "time": 1297286541
}
		

Never return nonsense.

More detailed...

1. Response only returns the timestamp
2. Media is not searchable by timestamp
3. Go through recent media (unkown size)
4. Parse until you found your last processed entry
5. Go back to 1. when there's an update

Realtime Streaming API

Streaming: The good

• realtime
• Realtime.
• REALTIME!

Streaming: The bad

• difficult to maintain connections over time
• lots of data

Example: Twitter

			Request: https://stream.twitter.com/1.1/statuses/filter.json
			Response: Full tweets
		

Don'ts: Twitter

Think of your customers

• Does it make sense to REST?
• Do you need push?
• Can you stream?

Analytics & Tracking

1. BYOA [Booya] (Build Your Own Analytics)
   http://www.productionhacks.com/2010/07/10/redis-api-access-logger/
2. NewRelic
   http://newrelic.com
3. Google Analytics
   https://github.com/skookum/nodealytics

Redis Tracking

Hit count

ZINCRBY 'api:requests:2010-07-10' 1 'users#update'

Increment a Sorted Set of daily “Controller#Action” values by User ID:

ZINCRBY 'api:requests:2010-06-30:users#update' 1 1337

Add the current date to a Set of dates for which we’re tracking data:

SADD api:requests:dates '2010-07-10'

Big Data

Upload your Redis database and query with Amazon Redshift or Google BigQuery

Cheap, non-intrusive history without vendor lock-in.

http://www.slideshare.net/supercoco9/api-analytics-with-redis-and-google-bigquery-nosql-matters-edition

NewRelic

Errors

Errors

Or: be smart, follow standards!

Example: BrainTree API

log(error, result);

null, ...

Example: BrainTree API

{ errors:
	{ validationErrors: {},
		errorCollections: { merchantAccount: [Object] } },
	params:
	{ merchantAccount:
			{ applicantDetails: [Object],
				tosAccepted: 'true',
				masterMerchantAccountId: 'xx',
				id: 'xx' },
		action: 'create_via_api',
		controller: 'merchant_accounts',
		merchantId: 'xx' },
	message: 'Master merchant account ID is invalid.',
	success: false }

The Excuse

An invalid account ID isn't a serious error. https://github.com/braintree/braintree_node/issues/20#issuecomment-28726370

Log!

• http://mixu.net/minilog/ or other log tools
• https://airbrake.io
• https://www.getsentry.com
• https://www.loggly.com

Summary

• Logging: Be the first to know if there are issues
• Analytics: See what your users are doing
• Tracking: Provide data to your company
• Types: Provide people with what they need, not what's RESTful
• Security: Your customers data. Keep it safe.

Summary

• An API is a business asset.
• An API provides value.
• You don't just generate a REST API
• People rely on your API
• People experience your API, make it a good experience

Questions?

Get in touch!
@PatrickHeneise
themobilefirm.co
patrickheneise.com