APIs
An exploration into the past, present, and
future parts of web microservice and their
place in current modern tech culture.
Slide 2
Slide 2 text
APIs
What is an API?
Slide 3
Slide 3 text
Why APIs?
Slide 4
Slide 4 text
Mobile Devices
Slide 5
Slide 5 text
JS Frameworks
Slide 6
Slide 6 text
Email?
SMS?
Twitter?
Slide 7
Slide 7 text
Me
Slide 8
Slide 8 text
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
Slide 9
Slide 9 text
History
Slide 10
Slide 10 text
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)
Slide 11
Slide 11 text
History, Quickly
• Software worked over the “network”
before the internet
• They would connect via “APIs” to a
remote server.
• Known as “Client/Server”
Slide 12
Slide 12 text
History, Quickly
• The “internet” resembled this
• People said, let’s expose “data” over the
internet via an “API”
• It stuck
Slide 13
Slide 13 text
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
Slide 14
Slide 14 text
Headers
• Both requests and responses contain
“headers”
• Headers are sent/received with all
requests/responses
• They help browsers and computers do
their thing
Slide 15
Slide 15 text
The Request
Slide 16
Slide 16 text
It’s called a Request no matter if you
are requesting data or sending data
Slide 17
Slide 17 text
Requests
• URL
• Method
• Content-Type
• Accepts
Slide 18
Slide 18 text
URL
http://www.domain.com/users/56
Protocol Domain Path
Resource ID
Slide 19
Slide 19 text
URL
• Each “Entity” has one specific URL.
• The best URLs are “guessable”
Slide 20
Slide 20 text
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
Slide 21
Slide 21 text
Content Type
• Specified via a “HEADER”
• When sending data (POST/PATCH), tells
server if you’re sending JSON or XML or
JWOML
Slide 22
Slide 22 text
Accept
• Specified via a “HEADER”
• Tells server what type of data you want to
receive back, such as JSON, XML, or
JWOML
Slide 23
Slide 23 text
The Response
Slide 24
Slide 24 text
Status Code
• Specified via a “HEADER”
• Tells the client all sorts of things
Slide 25
Slide 25 text
OK Status Codes
• 200: OK
• 201: Created
• 301: Over there (always)
• 302: Over there (temporarily)
Slide 26
Slide 26 text
NotGreat Status Codes
• 400: Generic Bad, but your bad
• 401: You are not authenticated
• 404: Not Found
• 422: Errors found in your data
Slide 27
Slide 27 text
RealBad Status Codes
• 500: Big huge problem, it’s my fault
• 503: Service is down
Slide 28
Slide 28 text
General Status Codes
• 200: OK
• 300: Over There
• 400: [BLEEP] You
• 500: [BLEEP] Me
Slide 29
Slide 29 text
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
Slide 30
Slide 30 text
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
Slide 31
Slide 31 text
Exchange Rates
response.rates.AUD
Slide 32
Slide 32 text
GitHub Repos
[0].owner.login
Slide 33
Slide 33 text
JSON API Sample
data[0].attributes.title
Slide 34
Slide 34 text
Shape of Data
• Sometimes the base object is a key,
sometimes it’s an array
• When you get this wrong, it brakes
Slide 35
Slide 35 text
Tools
Slide 36
Slide 36 text
Without JSON-View
Formats JSON in Browsers
Slide 37
Slide 37 text
With JSON-View
Formats JSON in Browsers
Slide 38
Slide 38 text
Postman
Set headers, post data, receive data
Slide 39
Slide 39 text
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
Slide 40
Slide 40 text
Authentication
Slide 41
Slide 41 text
Authentication
Who You are
Slide 42
Slide 42 text
Authentication
What App Are You Using?
Slide 43
Slide 43 text
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.
Slide 44
Slide 44 text
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
Slide 45
Slide 45 text
Authorization
\What You Can See
Slide 46
Slide 46 text
Oauth
Slide 47
Slide 47 text
Way for Internet users to authorize websites or
applications to access their information on other
websites but without giving them the passwords.
Slide 48
Slide 48 text
Way for Internet users to authorize websites or
applications to access their information on other
websites but without giving them the passwords.
Slide 49
Slide 49 text
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
Slide 50
Slide 50 text
It’s Just That Easy™
Slide 51
Slide 51 text
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
Slide 52
Slide 52 text
Standards
(attempts)
Slide 53
Slide 53 text
JSON-API
• Created by the EmberJS team, JSON-API
attempts to standardize the shape of the
JSON responses
• Results outside of Ember: not-great
Slide 54
Slide 54 text
GraphQL
• “Hot Future” of JSON-APIs.
• Query for what you want, instead of
returning ALL data.
Slide 55
Slide 55 text
PRO Tips
Slide 56
Slide 56 text
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
Slide 57
Slide 57 text
JSON-P
• Can cross CORS boundary
• You specify a callback to be called by
server
• (I’d rather just have a proxy)
Slide 58
Slide 58 text
More Logging
• console.log() the response you actually
get
• Don’t assume documentation is up to
date, accurate, or nice
Slide 59
Slide 59 text
Great APIs Have
Slide 60
Slide 60 text
Great Expectations
• Versioning
• API Keys
• Runnable Documentation
• Sample Libraries
• Does just about what you’d expect