Notes on Zapier’s "An Introduction to APIs"

Author

Josh Livingston

Published

July 16, 2023

Introduction

This document contains my notes on Zapier’s An Introduction to APIs, which is recommended as foundational reading for those who are new to APIs and intending to build an API Package using httr.

Chapter 1: Introduction

Link to chapter

An API is just a set of rules (interface) that the [server and client] agree to follow.

  • Servers, simply put, are computers
    • Web servers continuously run the programs (APIs) loaded onto them
      • These programs wait for a request to generate a web page
  • APIs:
    1. Make a website’s data accessible
    2. Integrate the server (program) and client (user)
  • Key terms:
    • Server: A powerful computer that runs an API
    • API: The “hidden” portion of a website that is meant for computer consumption
    • Client: A program that exchanges data with a server through an API

Chapter 2: Protocols

Link to chapter

A computer protocol an accepted set of rules that govern how two computers can speak to each other.

  • Protocols can be thought of as “etiquette for computers” - rules that guide interaction
    • Computer etiquette, in contrast to social etiquette, is extremely rigid
    • Rigidity in this case means communication must be specifically arranged

HTTP

  • HTTP is the ubiquitous protocol for the web
  • HTTP involves requests and responses between the server and the client
  • The request-response cycle is comprised of five pieces:
Requests Responses
URL ✅ ❌
Method ✅ ❌
Headers ✅ ✅
Body ✅ ✅
Status Code ❌ ✅
  1. A URL (Uniform Resource Locator) is the “noun” of an API request - a unique address that points to a program’s resources
  2. The request’s method (the verb) answers the question “What kind of action should be taken?”:
    1. GET (retrieve)
    2. POST (create)
    3. PUT (modify)
    4. DELETE (delete)
  3. Headers provide meta-information about a request or response (e.g. mobile vs desktop)
  4. The body contains the data for the request or response
  5. The status code is a three digit number that communicates the response’s result

Chapter 3: Data formats

Link to chapter

A well-designed format is dictated by what makes the information the easiest for the intended audience to understand.

  • Data is arranged into a commonly-understood format, usually either JSON (JavaScript Object Notation or XML (Extensible Markup Language)

  • Data formats can be noted in both requests and responses

    • In a response, the Content-Type header can be set to specify the format of the data included in the response
    • In a request, the Accept header can be set to specify the data format required by the client

JSON

  • JSON represents data in key-value pairs

    • Keys identify the attribute of the object being described
    • Values contain the object’s descriptions corresponding to each attribute
    • Pairs can be nested as associative arrays

XML

  • XML represents data in building blocks called nodes
    • Each object starts with a root node; subsequent nodes are nested inside
    • Each item in the object is represented by its own node

Chapters 4 + 5: Authentication

Link to Chapter 4

Link to Chapter 5

When you authenticate with a server, you prove your identity to the server by telling it information that only you know [hopefully].

  • Authentication is a process that proves the client’s identity to the server using credentials

  • Authentication schemes are techniques an API uses to authenticate a client

Basic Authentication

  • Basic authentication is an authentication scheme that uses two credentials: a username and password

    1. These credentials are combined, encoded, and passed to the request in a header called authorization

    2. If there is no match to credentials on the server, a status code (401) is returned in the response, indicating a failed authentication

  • Security is a concern when using basic authentication:

    • Access must be made completely open for all authorized users due to econding
    • No way to prevent being locked out of an owned account when sharing username and password

API Key Authentication

  • API key authentication is an authentication scheme using an API key, a unique string assigned to each user of an API

  • API key authentication provides two main benefits over basic authentication:

    • The unique key allows access to the API to be controlled at the user level

    • The unique key allows users to share their API access while limiting account access (e.g., changing an account password)

  • No standard exists for API key authentication, but two implementations are more common:

    1. Add the API key to the authorization header

    2. Add the API key to the URL

Chapter 6: API Design

Link to Chapter

Chapter 7: Real-Time Communication

Link to Chapter

Chapter 8: Implementation

Link to Chapter