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

Twitter

PagerDuty

Freshdesk

Using a RESTful API

Any web browser
Command-line (cURL)
GUI HTTP Client (Postman)
Web-based HTTP Client (Runscope)

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!