datahero / eventbrite - api best practices

26
© 2014 DataHero, Inc. Confidential and Proprietary JeZabel je@datahero.com @jczabel

Upload: jeff-zabel

Post on 13-Jul-2015

323 views

Category:

Engineering


4 download

TRANSCRIPT

Page 1: DataHero / Eventbrite - API Best Practices

© 2014 DataHero, Inc. Confidential and Proprietary

Jeff Zabel [email protected] @jczabel

Page 2: DataHero / Eventbrite - API Best Practices

DataHero delivers a self-service Cloud BI solution that enables enterprise and SMB users to analyze and visualize their SAAS-based data without IT

© 2014 DataHero, Inc. Confidential and Proprietary

WHAT WE DO

Page 3: DataHero / Eventbrite - API Best Practices

THE EMERGING CLOUD BI MARKET

Page 4: DataHero / Eventbrite - API Best Practices

DATAHERO: API EXPERTS

© 2014 DataHero, Inc. Confidential and Proprietary

Page 5: DataHero / Eventbrite - API Best Practices

© 2014 DataHero, Inc. Confidential and Proprietary

BUSINESS INTEGRATIONS

WRITTEN 26 INTEGRATIONS & COUNTING  

Page 6: DataHero / Eventbrite - API Best Practices

OPTIMIZED DATA INGEST FRAMEWORK

CUSTOM CONNECTORS •  High-speed connectors built in

collaboration with partners for optimal performance

•  Robust, extensible framework supports rapid development of new connectors

•  Secure integrations leverage partner security models for consistent data visibility

EXTENSIBLE CONNECTION FRAMEWORK

CONNECTOR

CONNECTOR

CONNECTOR

Page 7: DataHero / Eventbrite - API Best Practices

GETTING STARTED

© 2014 DataHero, Inc. Confidential and Proprietary

Page 8: DataHero / Eventbrite - API Best Practices

DEFINE YOUR API USE CASES SINGLE USER / DEVELOPER MULTIPLE USERS

EXPERIENCED DEVELOPER INEXPERIENCED DEVELOPER

Page 9: DataHero / Eventbrite - API Best Practices

HELP ME GET STARTED •  Create a friendly subdomain – developer.yourcompany.com

•  Provide a nice high level overview of your sections and some way to navigate them: •  Getting started / Quick Start •  Documentation

•  API Reference Docs •  Tutorials or Code Samples

•  Authentication •  Extras

Page 10: DataHero / Eventbrite - API Best Practices

EASY TO REGISTER

•  Make it obvious how to register my application

•  Can I use your product for free? •  If no and you want 3rd parties to develop applications, make it easy to

create a developer account •  Find the right way in your business to enable a developer or sandbox

account

•  Enable me to customize my application on your site •  Add my URLS •  Add contact information •  Upload my branding or logo

CLEAR CALL TO ACTION

Page 11: DataHero / Eventbrite - API Best Practices

LIMITATIONS / UNIQUE •  Tell me about restrictions

•  Quotas •  Rate Limits •  Terms of Service

•  Give me a clear description of your error codes & make sure even your proxies return in the appropriate api response type

•  Anything I should know that makes your API Unique •  Do you have an Export API

Page 12: DataHero / Eventbrite - API Best Practices

AUTHENTICATION

© 2014 DataHero, Inc. Confidential and Proprietary

Page 13: DataHero / Eventbrite - API Best Practices

AUTHENTICATION

API KEYS •  Allows you to generate unique

“passwords” for api usage. •  Arguably easier to implement than Oauth •  If you create this, consider allowing

unique “users” or API keys for various applications

OAUTH 2.0 •  Arguably the most secure method •  Allows users to easily revoke

applications one by one •  Provides a trusted and safe

credential page •  Allows you as the API provider to

understand how many installs a particular application has

PERSONAL EXPERIENCE Authentication is probably one of the most important parts of your API. It is your first impression. If it is difficult to get authenticated or get your application keys, it leaves a bitter taste in your mouth.

Page 14: DataHero / Eventbrite - API Best Practices

OAUTH

TIPS •  Provide different application keys for different domains

•  Prevent your keys from being used on another domain

•  Implement the optional “Revoke” token method

•  Use OAuth 2.0, but if you use 1.0, make it obvious to developers

•  Use scopes to limit access or permissions •  Create a read vs write permission •  Control access to various components

•  Configure to allow access token request via HTTP Post

Page 15: DataHero / Eventbrite - API Best Practices

IMPLEMENTATION & DOCUMENTATION

© 2014 DataHero, Inc. Confidential and Proprietary

Page 16: DataHero / Eventbrite - API Best Practices

DOCUMENTATION IT GOES WITHOUT SAYING

If authentication is your first impression, documentation is your overall appearance.

Page 17: DataHero / Eventbrite - API Best Practices

REST VS SOAP •  Base URI: http://example.com/resources •  Define the response media type: JSON, XML, etc •  Standard HTTP methods (GET, POST, PUT, DELETE)

Resource GET PUT POST DELETE Collection URI http://example.com/charts

List all the charts Replace the entire collection

Create a new entry in the collection

Delete the entire collection

Element URI http://datahero.com/chart/123

Retrieve a single chart

Replace the single member of the collection or create it if it doesn’t exist

Delete the single member of the collection

OPINION ON SOAP It’s not 1998 anymore. Move on. In our integrations, we’re seeing a movement from SOAP to REST from the “older” or more “established” technology companies

Page 18: DataHero / Eventbrite - API Best Practices

SERVICE ENDPOINTS MAKE YOUR RESPONSES RESTFUL & CLEARLY DEFINE YOUR ENDPOINTS

METHOD NAME HTTP METHOD

DESCRIPTION

Page 19: DataHero / Eventbrite - API Best Practices

RESPONSE OBJECTS CLEARY DEFINE THE RESPONSE OBJECT

ENDPOINT DETAILED DESCRIPTION EXAMPLE RESPONSE

Page 20: DataHero / Eventbrite - API Best Practices

XML OR JSON

TAKEAWAY:

Unless you really have a good reason, do yourself a favor and just use JSON.

XML •  Allows you to define an extremely rigid

data structure. •  Name spacing and extensibility •  Flexibility

JSON •  Has become the “defacto” standard

response of REST apis

•  Most new modern languages support easy parsing (Ruby, Node.js, Python)

•  Structure is easily imported into nosql databases and big data stores

•  Is more lightweight and less verbose

Page 21: DataHero / Eventbrite - API Best Practices

CLIENT LIBRARIES

•  Make it easy for less experienced developers to get started

•  Enables you to test your API if you create a generated client

•  DataHero has created 6 node.js clients for partners: •  node-eventbrite •  node-exacttarget •  node-hubspot •  node-marketo •  node-pardot •  Surveymokey

•  And contributed to even more •  node-mailchimp •  node-recurly •  node-zendesk

Page 22: DataHero / Eventbrite - API Best Practices

VERSIONING

•  JSON is awesome, but change can be hard

•  You’re going to change, so make it easy and create api versioning

•  Allow your old endpoints to survive – remember that others might not move as fast as you

Page 23: DataHero / Eventbrite - API Best Practices

DEMO ACCOUNTS

THE EMPTY STATES OF APIS Would you create a web application without good empty states? Then don’t do it with your API

COOL IDEA: Create a communal account that developers can use

Page 24: DataHero / Eventbrite - API Best Practices

COMMUNITY FORUMS ENABLE THE COMMUNITY TO HELP OUT •  Posts questions on use cases, helpful tips, bugs, etc.

•  Help guide your company on what to create next (or enable 3rd party developers to do it for you)

•  Doesn’t take much to get started, simply a Google Group or Uservoice will do

Page 25: DataHero / Eventbrite - API Best Practices

WEBHOOKS

PUSH YOUR INFORMATION OUT •  Do you have information that would be useful to provide as alerts, then use

webhooks

•  Any server can listen for these changes and then update your application accordingly

•  Make sure to create a degrading re-try mechanism on your requests

Page 26: DataHero / Eventbrite - API Best Practices

© 2014 DataHero, Inc. Confidential and Proprietary

Jeff Zabel [email protected] @jczabel WE’RE HIRING!