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!

RESTful APIs

By Jett Durham

Made with Slides.com

RESTful APIs

This presentation goes into what a RESTful API is, why we use them, and how they work.

  • 1,186

More from Jett Durham