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.
   

   View Slide

2. APIs
   What is an API?
   

   View Slide

3. Why APIs?
   

   View Slide

4. Mobile Devices
   

   View Slide

5. JS Frameworks
   

   View Slide

6. Email?
   SMS?
   Twitter?
   

   View Slide

7. Me
   

   View Slide

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
   

   View Slide

9. History
   

   View Slide

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)
    

    View Slide

11. History, Quickly
    • Software worked over the “network”
    before the internet
    • They would connect via “APIs” to a
    remote server.
    • Known as “Client/Server”
    

    View Slide

12. History, Quickly
    • The “internet” resembled this
    • People said, let’s expose “data” over the
    internet via an “API”
    • It stuck
    

    View Slide

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
    

    View Slide

14. Headers
    • Both requests and responses contain
    “headers”
    • Headers are sent/received with all
    requests/responses
    • They help browsers and computers do
    their thing
    

    View Slide

15. The Request
    

    View Slide

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

    View Slide

17. Requests
    • URL
    • Method
    • Content-Type
    • Accepts
    

    View Slide

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

    View Slide

19. URL
    • Each “Entity” has one specific URL.
    • The best URLs are “guessable”
    

    View Slide

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
    

    View Slide

21. Content Type
    • Specified via a “HEADER”
    • When sending data (POST/PATCH), tells
    server if you’re sending JSON or XML or
    JWOML
    

    View Slide

22. Accept
    • Specified via a “HEADER”
    • Tells server what type of data you want to
    receive back, such as JSON, XML, or
    JWOML
    

    View Slide

23. The Response
    

    View Slide

24. Status Code
    • Specified via a “HEADER”
    • Tells the client all sorts of things
    

    View Slide

25. OK Status Codes
    • 200: OK
    • 201: Created
    • 301: Over there (always)
    • 302: Over there (temporarily)
    

    View Slide

26. NotGreat Status Codes
    • 400: Generic Bad, but your bad
    • 401: You are not authenticated
    • 404: Not Found
    • 422: Errors found in your data
    

    View Slide

27. RealBad Status Codes
    • 500: Big huge problem, it’s my fault
    • 503: Service is down
    

    View Slide

28. General Status Codes
    • 200: OK
    • 300: Over There
    • 400: [BLEEP] You
    • 500: [BLEEP] Me
    

    View Slide

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
    

    View Slide

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
    

    View Slide

31. Exchange Rates
    response.rates.AUD
    

    View Slide

32. GitHub Repos
    [0].owner.login
    

    View Slide

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

    View Slide

34. Shape of Data
    • Sometimes the base object is a key,
    sometimes it’s an array
    • When you get this wrong, it brakes
    

    View Slide

35. Tools
    

    View Slide

36. Without JSON-View
    Formats JSON in Browsers
    

    View Slide

37. With JSON-View
    Formats JSON in Browsers
    

    View Slide

38. Postman
    Set headers, post data, receive data
    

    View Slide

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
    

    View Slide

40. Authentication
    

    View Slide

41. Authentication
    Who You are
    

    View Slide

42. Authentication
    What App Are You Using?
    

    View Slide

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.
    

    View Slide

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
    

    View Slide

45. Authorization
    \What You Can See
    

    View Slide

46. Oauth
    

    View Slide

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

    View Slide

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

    View Slide

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
    

    View Slide

50. It’s Just That Easy™
    

    View Slide

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
    

    View Slide

52. Standards
    (attempts)
    

    View Slide

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
    

    View Slide

54. GraphQL
    • “Hot Future” of JSON-APIs.
    • Query for what you want, instead of
    returning ALL data.
    

    View Slide

55. PRO Tips
    

    View Slide

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
    

    View Slide

57. JSON-P
    • Can cross CORS boundary
    • You specify a callback to be called by
    server
    • (I’d rather just have a proxy)
    

    View Slide

58. More Logging
    • console.log() the response you actually
    get
    • Don’t assume documentation is up to
    date, accurate, or nice
    

    View Slide

59. Great APIs Have
    

    View Slide

60. Great Expectations
    • Versioning
    • API Keys
    • Runnable Documentation
    • Sample Libraries
    • Does just about what you’d expect
    

    View Slide

61. Publishing APIs
    

    View Slide

62. Microservices
    • JavaScript: Express, KOA, HAPI
    • Ruby: Sinatra
    • C#: Nancy
    • Swift: Taylor
    

    View Slide

63. Larger Frameworks
    • Node: Adonis
    • Ruby: Rails
    • C#: ASP.NET MVC
    • Swift: Vapor / Perfect
    

    View Slide