RESTful APIs
A short story of what, why and how
Image Credit: cloud-elements.com
Talk Overview
- What is an API?
- REST & RESTful APIs
- HTTP Basics
- Using RESTful APIs
What is an API?
Application
In networking context,
Web Service is also used
Programming
Interface
Image Credit: Maxim Basinski
APIs allow two applications to communicate in a common language
Communication can be
- Retrieving Data
- Sending Data
- Running Procedures
{
Image Credit: moz.com
Network APIs allow applications to communicate across language barriers
- Clients
- Frontend
- Consumer
- Server
- Backend
- Provider
This can be implemented in any language
Image Credit: learnx
A Few More Definitions
- Resource - The data/procedure on the server
- Message - Data being sent by a client or from a server
- Endpoint - Location on the server where resource is accesible
- Payload - Same as message, usually refers to data being sent to server
- Consume - To use an API
REST &
RESTful APIs
Representational State Transfer
- Not a protocol per se, it's "just the way the web works"
- Messages are exchanged directly in HTTP requests and responses
- Data is usually encoded in JSON, but doesn't have to be
- APIs that speak in bare HTTP are called RESTful APIs
The Rise of RESTful APIs
- Smaller Request/Response Body sizes: Faster!
- Client and Server code is much simpler to write/maintain
- Simple endpoint testing can be performed in a web browser
HTTP Basics
HTTP Requests
https://api.twitter.com/1.1/users/suggestions.json?id=foo&name=bar
Protocol
URI
Route
^
Version
Query String
- HTTP Method - Describes action performed by request (GET, POST, PUT, etc.)
- Headers - Key-Value pairs (API Authentication typically goes here)
- Body - Content to be sent to server (only for some types of requests)
Other Request Parts
HTTP Responses
[
{
"name": "Art & Design",
"slug": "art-design",
"size": 20
},
{
"name": "Billboard Music Awards",
"slug": "billboard-music-awards",
"size": 20
},
{
"name": "Books",
"slug": "books",
"size": 20
},
{
"name": "Business",
"slug": "business",
"size": 20
},
{
"name": "CMT Awards",
"slug": "cmt-awards",
"size": 20
},
{
"name": "Charity",
"slug": "charity",
"size": 20
},
{
"name": "Entertainment",
"slug": "entertainment",
"size": 20
},
{
"name": "Faith and Religion",
"slug": "faith-and-religion",
"size": 20
},
{
"name": "Family",
"slug": "family",
"size": 20
},
{
"name": "Fashion",
"slug": "fashion",
"size": 20
},
{
"name": "Food & Drink",
"slug": "food-drink",
"size": 20
},
{
"name": "Funny",
"slug": "funny",
"size": 20
},
{
"name": "Government",
"slug": "government",
"size": 20
},
{
"name": "Health",
"slug": "health",
"size": 20
},
{
"name": "MLB",
"slug": "mlb",
"size": 20
},
{
"name": "MTV Movie Awards",
"slug": "mtv-movie-awards",
"size": 20
},
{
"name": "Music",
"slug": "music",
"size": 20
},
{
"name": "NASCAR",
"slug": "nascar",
"size": 20
},
{
"name": "NBA",
"slug": "nba",
"size": 20
},
{
"name": "NHL",
"slug": "nhl",
"size": 20
},
{
"name": "News",
"slug": "news",
"size": 20
},
{
"name": "PGA",
"slug": "pga",
"size": 20
},
{
"name": "Science",
"slug": "science",
"size": 20
},
{
"name": "Sports",
"slug": "sports",
"size": 20
},
{
"name": "Staff Picks",
"slug": "staff-picks",
"size": 20
},
{
"name": "Technology",
"slug": "technology",
"size": 20
},
{
"name": "Television",
"slug": "television",
"size": 20
},
{
"name": "Travel",
"slug": "travel",
"size": 20
},
{
"name": "Twitter",
"slug": "twitter",
"size": 20
},
{
"name": "US Election 2012",
"slug": "us-election-2012",
"size": 20
}
]
Body
- Response Code - Status of request. Defined by HTTP Standards
- Headers - Same format as Request headers
Other Response Parts
HTTP Methods
- GET - Used to retrieve data
- POST - Used for adding new data
- PUT - Used for replacing existing data
- PATCH - Used for partially modifying existing data
- DELETE - Used for deleting data
- HEAD - Same as GET, but must not return a response body
- OPTIONS - Used for getting information about a resource
There are standards for HTTP Methods, but it's up to the API author to implement them correctly
Using a RESTful API
Reading API Documentation
- Available routes and/or actions
- HTTP Methods available for each route
- Authentication requirements
- Accepted Headers and/or Query Parameters
- Example requests & responses
Documentation varies widely between API authors, but there are several things you can expect to find
Example API Docs
Using a RESTful API
In production, you'll make HTTP requests from your application
However, for testing or learning purposes, you can make and send them directly!
ProTip: Don't forget about the OPTIONS method when learning a new API!
Talk Recap
- APIs are how applications talk over the internet
- REST is basically plain HTTP, data usually in JSON
- HTTP provides a rich feature-set for packaging actions and data
- Getting data in and out of RESTful APIs is as easy as typing a url, but very powerful!
RESTful APIs
By Jett Durham
RESTful APIs
This presentation goes into what a RESTful API is, why we use them, and how they work.
- 1,329