What is an API

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

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