Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Your API is Bad and You Should Feel Bad

532 views

Published on

More devices than ever are connected to the Internet these days, and the need and consumption of APIs is growing fast. We'll talk about what an API is (and what it's not), why you might need one, how you might use one, and how to make one that other people will enjoy using.

Published in: Technology
  • Be the first to comment

Your API is Bad and You Should Feel Bad

  1. 1. SouthEast LinuxFest 2015 Your API is Bad and You Should Feel Bad Amanda Folson AmbassadorAwsum
  2. 2. SouthEast LinuxFest Who am I to judge? • Associate Product Manager/Developer Evangelist at PagerDuty • Average consumer of APIs and IPAs • Well RESTed (you can boo at my pun) • Professional conference attendee and tinkerer 6/17/2015Your API is Bad and You Should Feel Bad
  3. 3. SouthEast LinuxFest APIs are Everywhere 6/17/2015
  4. 4. SouthEast LinuxFest Great, but why do I care? • Provides a uniform interface for interacting with your application • API allows you to shard off services – Decouples services – Website->API – Mobile->API • This is cool if you’re into SoA – I am. 6/17/2015
  5. 5. SouthEast LinuxFest Types of Application Programming Interfaces • Language/Platform/Library APIs – Win32 – C++ – OpenGL • Web APIs – SOAP – XML-RPC – REST 6/17/2015
  6. 6. SouthEast LinuxFest SOAP • Stateful • WS-Security • Mostly obvious procedures (getRecord, delRecord) – Need to know procedure name – Need to know order of parameters 6/17/2015
  7. 7. SouthEast LinuxFest REST • Gaining adoption • HTTP-based (usually) • No need to know order of parameters in most cases • Can return XML, JSON, ? 6/17/2015
  8. 8. SouthEast LinuxFest Sounds Good, Let’s Build 6/17/2015
  9. 9. SouthEast LinuxFest “The best design is the simplest one that works.” 6/17/2015 Albert Einstein Your API is Bad
  10. 10. SouthEast LinuxFest Slow Down • Don’t rush into v1, v2, etc. • Make sure you meet goals • Involve users/engineers from the start • This is hard 6/17/2015
  11. 11. SouthEast LinuxFest IncrediBL Overview • DNSBL (lists IPs to blacklist) • Requires DNS servers – Lookups – Domain resolution • Requires database servers • Requires web servers • Requires patience 6/17/2015
  12. 12. SouthEast LinuxFest Design • Immutable blueprint • Contract between you and users • SHARE – The worst feedback is the feedback you don’t hear • Account for existing architecture • Changes should provide actual value not perceived/potential value • Design for uniformity 6/17/2015
  13. 13. SouthEast LinuxFest Know Thy Audience • Who is this for? – Us? Internal? – Them? Business partners/3rd parties? – ??? • What’s the incentive? 6/17/2015
  14. 14. SouthEast LinuxFest Ask! • Stakeholders will tell you what they need • Regardless of version, feedback should make it into your spec • Build something people want 6/17/2015
  15. 15. SouthEast LinuxFest Spec Tools • Apiary/API Blueprint • Swagger • RAML The list goes on… 6/17/2015
  16. 16. SouthEast LinuxFest What is REST? • Representational State Transfer • HTTP-based routing and methods – PUT/GET/POST/etc. • Stateless – No sessions – HATEOAS 6/17/2015
  17. 17. SouthEast LinuxFest Resources • /resource is a gateway to an area of your application – /users – /places – /things • CRUD actions can be performed on a single resource – GET vs getUser, getMessage, getThing • Use plural nouns, no verbs (GET, CREATE, etc.) – Can be for a single item or a collection of items 6/17/2015
  18. 18. SouthEast LinuxFest Action Verbs 6/17/2015
  19. 19. SouthEast LinuxFest GET • GET data from a /resource • You do this daily by browsing the web. Go you. • Uses query string to tell API what data to retrieve • Returns 200 if everything’s OK 6/17/2015
  20. 20. SouthEast LinuxFest POST • Used to create/manipulate data • Relies on a message body being sent vs query string (XML, JSON, ?) • Returns 201 Created • Should return URI to newly created resource 6/17/2015
  21. 21. SouthEast LinuxFest PUT • Update a resource • OVERWRITES EXISTING OBJECT WITH NEW ONE – You don’t have to allow this, be careful with this because its use is inconsistent across APIs, should be used consistently across resources – Return 201 created if you do this – Can’t use PUT within the resource itself (/messages) without an ID – PUT should never be use to wrangle partial updates 6/17/2015
  22. 22. SouthEast LinuxFest PATCH • Updates only the properties provided in the call • 200 on successful update • 304 if nothing changed 6/17/2015
  23. 23. SouthEast LinuxFest DELETE • Don’t allow on an entire collection (/users or /messages or /places) or limit it • 200 if item or collection was deleted • 204 if item or collection was deleted but there’s no body to return • 202 if request was accepted and deletion was queued (CDN, cache, etc.) 6/17/2015
  24. 24. SouthEast LinuxFest OPTIONS • Not for interacting with data • Informs clients of available methods • Return 200 or 204 • You could also return 405 (Method Not Allowed) but why would you do that you monster? • Useful when method should work on items but not collections within a resource (don’t DELETE and collection of users or messages) 6/17/2015
  25. 25. SouthEast LinuxFest Content Types • Be nice, return more than one – JSON and XML are common – Different clients have different needs – Easy to add new types as needed if you design for this early on • If you only allow one type, inform that others aren’t allowed • Use Content-type: to receive and parse client data • Can use Accept header to see what format client wants back • For simplicity you can just send back what they send 6/17/2015
  26. 26. SouthEast LinuxFest Replying • Provide information on failures beyond HTTP status codes. – “API Key does not have access to modify resource” is better than 403 Forbidden alone – 200 OK, 201 Created, 204 No Content, 304 Not Modified, 5xx We Screwed Up, Not You – HTTP status codes let client decide what to do next – No true standardized error message format, but Google Errors and JSON API are trying 6/17/2015
  27. 27. SouthEast LinuxFest HATEOAS • Hypermedia As The Engine Of Application State • Hypertext links to other resources (like links on a page) – Every object has actions to perform • Choose your own adventure for navigation/pagination – Give clients list of actions to take – Client tracks state – Server provides options to change state • HARD – Requires knowing possible ways to interact with object • Clients have to know how to handle this, some will hardcode anyway 6/17/2015
  28. 28. SouthEast LinuxFest Hypermedia Specs • Wishful thinking • There are no standards for this • JSON API? Custom? HAL? • HAL/JSON API are good starting points with wide adoption 6/17/2015
  29. 29. SouthEast LinuxFest Versioning • API is not the time to cowboy deploys/releases • Design so that you never have to version • Migrations are hard • Maintaining n versions • Deprecate carefully – Not everyone can update in a weekend 6/17/2015
  30. 30. SouthEast LinuxFest When to Version • Backwards incompatible changes – Creating new data models • When your API no longer meets you or your users’ needs BUT NOT • When you add new resources or data fields 6/17/2015
  31. 31. SouthEast LinuxFest Version in URI • https://api.myawesomestuff.com/v1/stuff • Version is obvious to users • Relative paths can’t always be hypermedia driven 6/17/2015
  32. 32. SouthEast LinuxFest Version in Content-type • Content-type: application/json+v1 • Cleaner, not as obvious • Can default to a version if none is specified • Devs need to know that they need to send this 6/17/2015
  33. 33. SouthEast LinuxFest Version in Custom Header • Version: 1 • MyApp: 2.6 • No standards • Requires GREAT docs • Confusing for users who aren’t expecting it 6/17/2015
  34. 34. SouthEast LinuxFest Caching • Ssscccaaallleee • Cache on API client end • Cache-control header (public, expires-at, no-cache, max-age), Expires • Important that this info end up in docs/SDKs 6/17/2015
  35. 35. SouthEast LinuxFest Authentication • Kill Basic Auth – Keep username/passwords safe • OAuth – Require users to explicitly authorize an app – Tricky for some people to implement – Restrict auth to HTTPS endpoints – Restrict domains allowed to auth – MITM attacks, make sure users store tokens well 6/17/2015
  36. 36. SouthEast LinuxFest Security • Treat users as hostile • Don’t rely on single method • Apply layers of security – Permissions-based API keys/UAC • Per app, not per account. Will depend on your architecture – DNSBL – Content length/depth limits • ¿Recursive? – SQL injection – Rate limit/throttling 6/17/2015
  37. 37. SouthEast LinuxFest Prototyping • Laravel/Lumen, Flask, Rails, Mojolicious – RESTful HTTP routing – Zero to API in ~1hr • Specs – Apiary, Mockable, RAML – Frameworks allow importing of specs – Some spec tools can autogenerate SDKs for you (APIMatic) • Chrome REST API client, Postman, jsfiddle 6/17/2015
  38. 38. SouthEast LinuxFest Now what? 6/17/2015
  39. 39. SouthEast LinuxFest Maintenance • Plan to maintain API, SDKs, docs • Don’t launch and leave • Allocate maintenance resources • Community? Paid service? 6/17/2015
  40. 40. SouthEast LinuxFest Things Bad People Do • Log in to view API docs – Counter to open source mentality to use docs as a lead generation tool • Use HTTP (needs more S) • No documentation • Require name/password in URL structure – Can be saved in browser/CLI which is very insecure 6/17/2015
  41. 41. SouthEast LinuxFest SDKs • Nice when these are provided to users • Should have maintenance plan like API • Need to be kept in sync • Should be made by language experts 6/17/2015
  42. 42. SouthEast LinuxFest Documentation • API is useless if no one knows how to use it • NEEDS to be part of design process • All inclusive – Errors/methods/parameters – Reference and tutorial – In sync with changes to API • Include how to get help • Open source is nice  6/17/2015
  43. 43. SouthEast LinuxFest The best API is the one that exists. 6/17/2015Your API is Bad and You Should Feel Bad
  44. 44. SouthEast LinuxFest /resources • Build APIs You Won’t Hate - Phil Sturgeon http://apisyouwonthate.com/ • Undisturbed REST - Mike Stowe http://mulesoft.com/restbook • Apiary – http://apiary.io • RESTful Web APIs - Leonard Richardson, Mike Amundsen, Sam Ruby 6/17/2015
  45. 45. Thank you. pagerduty.com SouthEast LinuxFest amanda@pagerduty.com http://amandafolson.net AmbassadorAwsum

×