APIs

(And Restaurants)

&

What is an API?

• Application Programming Interface
• A program (software) that is interacted with by other programs (as opposed to human users)
• It can be a web API, where requests are made to a server from a remote client (which is what we are building), but it can also be something like a programming library (a set of prebuilt functions that can be imported into a program)

Where our API Fits In

A user performs an action in an app client that makes a request to the app server

The app server makes a request to the Network API

The Network API fulfills the request and sends the data to the app server, which then sends the data back to the client

Relevant Concepts

• Specification
• Requests
• Architecture
• Servers
• Infrastructure
• Databases
• Events
• Background jobs
• Tech debt

Specification

• Describes how users can interact with the API
• Comprised of requests and their corresponding responses
• Tech example: (GET /users/123 responds with {name: Anakin})
• Analogical example: a restaurant menu

Requests

• A request is how information is accessed from an API
• A response is the fulfillment of a request
• Analogical examples:
  • Request – a restaurant customer ordering a meal
  • Response – the meal being served

Anatomy of a Request

• A request is made from a client (the program making the request) to a server (the program accepting the request)
• It is comprised of the following components:
  • An action/verb, e.g., GET, PUT, DELETE
  • An endpoint, e.g., /users/123
  • (Sometimes) a payload, e.g., name: Anakin
• ​It results in a response from the server and, sometimes, other actions, e.g., data being stored in a database

Architecture

• The design or structure of the API (similar to real-life archetecture)
• Analogical example: the layout of a restaurant, (including the dining area, kitchen, language spoken, design of tables and chairs, placement of the settings, etc.)

Servers

• Servers are programs that accept and fulfill requests from clients
• Sometimes computers are referred to as servers but, technically, the term 'server' is referring to the program(s) running on them
• Analogical example: the chefs/cooks in the kitchen preparing ingredients, cooking food, etc.

Infrastructure

• The actual machines that code, databases, etc. are running on
• Analogical example: the ovens, stoves, mixers, counters, etc. in a kitchen

Databases

• Application-wide data storage and retrieval
• Many different types for many different applications 
• Analogical example: The refrigerator and freezer

Search vs Transactions

• Search is when a client would like a relevant list of results that are (hopefully) related to a given input
• A transaction is when a client is asking for (or providing) something using an exact identifier
• Analogical examples:
  • Search: going to the produce section of the  grocery store to find vegetables for a salad
  • Transaction: scanning a products barcode to find its price, the isle it is stored on, etc.

Events

• An event refers to a notification after a specific action takes place
• An event is usually followed by some work (another action) being performed
• Analogical examples:
  • Event – a customer finishes eating
  • Following work – the check is brought to the customer

Background Jobs

• Work performed behind the scenes
• Technical example: an email being created and sent when a user forgets their password
• Analogical example: buspeople cleaning up tables, washing dishes, setting tables, etc.

Technical Debt

• Technical debt is accrued as a byproduct of creating software over a period of time
• It is often quite difficult to understand technical debt until after a product, or enchancement to an existing product is complete (or at least nearly complete)
• Analogical example: the mess created in a kitchen during service, wear and tear on cutlery, broken dinnerware, etc.