$30 off During Our Annual Pro Sale. View Details »

What is an API

What is an API

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

Jesse Wolgamott

February 24, 2017
Tweet

More Decks by Jesse Wolgamott

Other Decks in Technology

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