What is an API

What is an API

BEGINNER level on what is a (server-side JSON) API

3b5cb0411cbd1012acab1b60f7ce3606?s=128

Jesse Wolgamott

February 24, 2017
Tweet

Transcript

  1. APIs An exploration into the past, present, and future parts

    of web microservice and their place in current modern tech culture.
  2. APIs What is an API?

  3. Why APIs?

  4. Mobile Devices

  5. JS Frameworks

  6. Email? SMS? Twitter?

  7. Me

  8. Jesse Wolgamott • Former Instructor, Back-End Engineer at TIY Houston

    • Currently: Director, Back-end Engineering, The Iron Yard • Developer since 1997 • First JSON API: 2002
  9. History

  10. History, Quickly • API: “Application Programming Interface” • Standard input/output

    for a library to be used and re-used • Computers have APIs (BIOS, Hard Drives, Operating Systems)
  11. History, Quickly • Software worked over the “network” before the

    internet • They would connect via “APIs” to a remote server. • Known as “Client/Server”
  12. History, Quickly • The “internet” resembled this • People said,

    let’s expose “data” over the internet via an “API” • It stuck
  13. API Requests • There’s no difference between your browser requesting

    facebook.com and a computer program making an “API” call • facebook.com might return HTML to your browser and JSON to the program
  14. Headers • Both requests and responses contain “headers” • Headers

    are sent/received with all requests/responses • They help browsers and computers do their thing
  15. The Request

  16. It’s called a Request no matter if you are requesting

    data or sending data
  17. Requests • URL • Method • Content-Type • Accepts

  18. URL http://www.domain.com/users/56 Protocol Domain Path Resource ID

  19. URL • Each “Entity” has one specific URL. • The

    best URLs are “guessable”
  20. Method • Each Request has an HTTP-Method • GET ->

    request data • POST -> here’s new (or updated) data • DELETE -> delete data at this URL • PATCH -> here’s what to update
  21. Content Type • Specified via a “HEADER” • When sending

    data (POST/PATCH), tells server if you’re sending JSON or XML or JWOML
  22. Accept • Specified via a “HEADER” • Tells server what

    type of data you want to receive back, such as JSON, XML, or JWOML
  23. The Response

  24. Status Code • Specified via a “HEADER” • Tells the

    client all sorts of things
  25. OK Status Codes • 200: OK • 201: Created •

    301: Over there (always) • 302: Over there (temporarily)
  26. NotGreat Status Codes • 400: Generic Bad, but your bad

    • 401: You are not authenticated • 404: Not Found • 422: Errors found in your data
  27. RealBad Status Codes • 500: Big huge problem, it’s my

    fault • 503: Service is down
  28. General Status Codes • 200: OK • 300: Over There

    • 400: [BLEEP] You • 500: [BLEEP] Me
  29. Shape of Data • Each server will return different shapes

    of data • This is dependent of whatever developer happened to code that one day they were employed there
  30. Shape of Data • You have to exactly know the

    shape of data to get anything of value out of the API • You won’t know the shape of data until making calls and manually looking at data
  31. Exchange Rates response.rates.AUD

  32. GitHub Repos [0].owner.login

  33. JSON API Sample data[0].attributes.title

  34. Shape of Data • Sometimes the base object is a

    key, sometimes it’s an array • When you get this wrong, it brakes
  35. Tools

  36. Without JSON-View Formats JSON in Browsers

  37. With JSON-View Formats JSON in Browsers

  38. Postman Set headers, post data, receive data

  39. Essential Tools • You have to exactly know the shape

    of data to get anything of value out of the API • You won’t know the shape of data until making calls and manually looking at data • Sometimes you get documentation • Sometimes documentation is out of date
  40. Authentication

  41. Authentication Who You are

  42. Authentication What App Are You Using?

  43. User Authentication • User Authorization: Trade username and password for

    a token • All requests then contain token. • Without request, 401 • Token can be in Header or a URL parameter.
  44. App Authentication • Each App is given a token to

    use for the App itself • ApiToken is usually a Header, but can also be a URL parameter
  45. Authorization \What You Can See

  46. Oauth

  47. Way for Internet users to authorize websites or applications to

    access their information on other websites but without giving them the passwords.
  48. Way for Internet users to authorize websites or applications to

    access their information on other websites but without giving them the passwords.
  49. Two Types • Password Grant - used for me to

    trade my username/password on a site for an auth token • Sign in with Facebook / Google / Spotify / GitHub, etc
  50. It’s Just That Easy™

  51. Oauth Difficulty • Difficult to get the “Connect” oauth right

    • It is also the only responsible way to get a user’s information to your site from a second site
  52. Standards (attempts)

  53. JSON-API • Created by the EmberJS team, JSON-API attempts to

    standardize the shape of the JSON responses • Results outside of Ember: not-great
  54. GraphQL • “Hot Future” of JSON-APIs. • Query for what

    you want, instead of returning ALL data.
  55. PRO Tips

  56. CORS • Helps protect information • Feels like it gets

    in your way • If API protects against CORS, you use a server-side proxy to get around
  57. JSON-P • Can cross CORS boundary • You specify a

    callback to be called by server • (I’d rather just have a proxy)
  58. More Logging • console.log() the response you actually get •

    Don’t assume documentation is up to date, accurate, or nice
  59. Great APIs Have

  60. Great Expectations • Versioning • API Keys • Runnable Documentation

    • Sample Libraries • Does just about what you’d expect
  61. Publishing APIs

  62. Microservices • JavaScript: Express, KOA, HAPI • Ruby: Sinatra •

    C#: Nancy • Swift: Taylor
  63. Larger Frameworks • Node: Adonis • Ruby: Rails • C#:

    ASP.NET MVC • Swift: Vapor / Perfect