Table of Contents

• 1. The Beginning
  • 1.1. Introduction
  • 1.1.1. Who is this book for?
  • 1.1.2. Requirements
  • 1.1.3. How is this book organized?
  • 1.1.4. How To Read This Book
  • 1.1.5. Code Blocks
  • 1.1.6. Errors, Bugs, Problems
  • 1.2. A Short History of the Internet
  • 1.2.1. The Origin
  • 1.2.2. The Importance of Documentation (a.k.a Standards)
  • 1.2.3. Documentation
  • 1.2.4. The Web Standards Organizations
  • 1.2.5. The Different Types of “Standards”
  • 1.3. Getting Started
  • 1.4. Wrap Up
• 2. A Simple Sinatra API to Learn The Basics
  • 2.1. Building APIs with Sinatra
  • 2.2. Module Structure
  • 2.3. Creating Our First Sinatra API
  • 2.4. Understanding Resources
  • 2.4.1. URL, URI, IRI, URN, …
  • 2.4.2. HTTP and URIs
  • 2.4.3. Creating our first resource
  • 2.5. Wrap Up
• 3. Understanding HTTP Requests with curl
  • 3.1. Installing curl
  • 3.1.1. Installing on Mac OS X
  • 3.1.2. Installing on Linux
  • 3.2. curl Crash Course
  • 3.3. Our First curl Request
  • 3.4. HTTP Response
  • 3.4.1. The Start-Line
  • 3.4.2. The Header Fields
  • 3.4.3. The Empty Line
  • 3.4.4. The Message-Body
  • 3.5. HTTP Request
  • 3.5.1. The Start-Line
  • 3.5.2. The Header Fields
  • 3.5.3. The Empty Line
  • 3.5.4. The Message-Body
  • 3.6. Wrap Up
• 4. Media Type Fun
  • 4.1. Fixing our API
  • 4.2. Offering JSON and XML
  • 4.3. The Fundamental Issue With This Approach
  • 4.4. Following The RFC Recommendations
  • 4.5. Understanding Media Types
  • 4.5.1. Media Type
  • 4.5.2. MIME Type
  • 4.5.3. Content Type
  • 4.5.4. The Accept Header
  • 4.6. One Resource To Rule Them All
  • 4.7. Wrap Up
• 5. Using HTTP Verbs
  • 5.1. HTTP Methods, a.k.a “Verbs”
  • 5.1.1. What Is An HTTP Method?
  • 5.1.2. What Is A “Safe” Method?
  • 5.1.3. What Is An ‘Idempotent’ Method?
  • 5.2. Using All HTTP Verbs In Our API
  • 5.2.1. GET
  • 5.2.2. HEAD
  • 5.2.3. POST
  • 5.2.4. PUT
  • 5.2.5. PATCH
  • 5.2.6. DELETE
  • 5.2.7. OPTIONS
  • 5.2.8. TRACE & CONNECT
  • 5.2.9. LINK & UNLINK
  • 5.3. A Global Overview
  • 5.4. Wrap Up
• 6. Handling Errors
  • 6.1. The different classes of HTTP status codes
  • 6.2. Global
  • 6.2.1. 405 Method Not Allowed
  • 6.2.2. 406 Not Acceptable
  • 6.3. POST /users
  • 6.3.1. 415 Unsupported Media Type
  • 6.3.2. 400 Bad Request
  • 6.3.3. 409 Conflict
  • 6.4. GET /users/:first_name
  • 6.4.1. 404 Not Found
  • 6.4.2. 410 Gone
  • 6.5. PUT /users/:first_name
  • 6.6. PATCH /users/:first_name
  • 6.7. Wrap Up
• 7. Versioning
  • 7.1. Versioning Via Subdomain
  • 7.2. Versioning In The URL
  • 7.3. Versioning In The URL With a Parameter
  • 7.4. Versioning In A Custom Header
  • 7.5. Versioning With A Custom Media Type
  • 7.6. Accept Header With A Version Option
  • 7.7. No Versioning?
  • 7.8. Wrap Up
• 8. Caching
  • 8.1. Client Caching
  • 8.1.1. Preventing Requests Entirely
  • 8.1.2. Prevent Data Transfer
  • 8.1.3. Pre-Condition
  • 8.1.4. How Do Caches Store Different Representations of The Same Resource?
  • 8.1.5. Invalidating Cache
  • 8.1.6. Implementation
  • 8.2. Server Caching
  • 8.2.1. Implementation
  • 8.3. Wrap Up
• 9. Authentication
  • 9.1. Identification vs. Authentication vs. Authorization
  • 9.1.1. Identity
  • 9.1.2. Authentication
  • 9.1.3. Authorization
  • 9.2. Understanding The “Stateless” Constraint
  • 9.3. Authentication with HTTP
  • 9.3.1. Basic
  • 9.3.2. Digest
  • 9.3.3. Token
  • 9.3.4. API Keys
  • 9.4. A Note About OAuth 2.0
  • 9.5. Wrap Up
• 10. First Module Conclusion
  • 10.1. What Did You Learn?
  • 10.2. Conclusion
• 11. Alexandria
  • 11.1. Module Introduction
  • 11.2. Picking The Right Tool For The Job
  • 11.2.1. Rails 5 API Mode
  • 11.2.2. SQLite & PostgreSQL
  • 11.2.3. Testing
  • 11.2.4. Others
  • 11.3. Module Structure
  • 11.4. RESTful?
• 12. Alexandria: Setup Time
  • 12.1. Setting up our environment
  • 12.2. Creating the application
  • 12.3. Git
  • 12.3.1. Installing Git
  • 12.3.2. The Initial Commit
  • 12.3.3. Creating the GitHub repository
  • 12.3.4. Linking our local repository to GitHub
  • 12.4. Testing Environment
  • 12.4.1. Why Write Automated Tests?
  • 12.4.2. Different types of tests
  • 12.4.3. Setting Up The Tools
  • 12.5. Our First Test
  • 12.5.1. The Publisher Model
  • 12.5.2. RSpec Vocabulary
  • 12.5.3. Validation Test
  • 12.6. Pushing Our Changes
  • 12.7. Wrap Up
• 13. Adding Books and Authors
  • 13.1. The Author Model
  • 13.2. The Book Model
  • 13.3. Associations
  • 13.3.1. Author associations
  • 13.3.2. Publisher Associations
  • 13.3.3. Books Associations
  • 13.4. Handling Book Covers
  • 13.5. Pushing Our Changes
  • 13.6. Wrap Up
• 14. Exposing the Books Resource
  • 14.1. Creating the Controller
  • 14.2. The Index Action
  • 14.3. Returning Books
  • 14.4. Seeding Some Data
  • 14.5. Adding a RSpec Helper
  • 14.6. Pushing Our Changes
  • 14.7. Wrap Up
• 15. Building Representations
  • 15.1. Feature Requirements
  • 15.2. Crafting Our Own Tools
  • 15.3. Creating Presenters
  • 15.4. The FieldPicker class
  • 15.5. Playing With Our New Toy
  • 15.6. Pushing Our Changes
  • 15.7. Wrap Up
• 16. The First Query Builder: Paginator
  • 16.1. The Paginator builder
  • 16.2. Pagination with Kaminari
  • 16.3. Pagination Metadata
  • 16.4. Pagination Helper Method
  • 16.5. Updating the Books Controller
  • 16.6. Returning Errors
  • 16.7. Preparing For the Arrival of More Builders
  • 16.7.1. Updating the BasePresenter Class
  • 16.7.2. Updating the BookPresenter Class
  • 16.8. Pushing Our Changes
  • 16.9. Wrap Up
• 17. Query Builders
  • 17.1. Sorting Query Builder: Sorter
  • 17.1.1. Sorting in the Controller
  • 17.1.2. No! Extracting the Logic in a Dedicated Class
  • 17.1.3. Raising a QueryBuilderError
  • 17.1.4. Fixing the Books Controller
  • 17.2. Filtering Query Builder: Filter
  • 17.2.1. Implementing the Filter Class
  • 17.2.2. Handling Filtering
  • 17.2.3. Raising a QueryBuilderError
  • 17.2.4. Updating the Books Controller
  • 17.2.5. Playing with Filtering
  • 17.3. The EagerLoader Builder
  • 17.3.1. Adding the Author and Publisher Presenters
  • 17.3.2. Implementing the EagerLoader Class
  • 17.4. Pushing Our Changes
  • 17.5. Wrap Up
• 18. Representation Builders
  • 18.1. Updating the FieldPicker
  • 18.1.1. Refactoring the FieldPicker
  • 18.1.2. Adding a New Error: RepresentationBuilderError
  • 18.1.3. Updating the Controllers
  • 18.2. EmbedPicker
  • 18.2.1. Implementing the EmbedPicker
  • 18.2.2. Updating the Controllers
  • 18.2.3. Eager Loading
  • 18.3. QueryOrchestrator
  • 18.4. Serializer
  • 18.5. Pushing our Changes
  • 18.6. Wrap Up
• 19. Finishing Up Our Controllers
  • 19.1. The Books Controller
  • 19.1.1. GET /api/books
  • 19.1.2. GET /api/books/:id
  • 19.1.3. POST /api/books
  • 19.1.4. PUT /api/books/:id
  • 19.1.5. PATCH /api/books/:id
  • 19.1.6. DELETE /api/books/:id
  • 19.2. The Authors Controller
  • 19.3. The Publishers Controller
  • 19.4. Uploading Book Covers
  • 19.5. Pushing Our Changes
  • 19.6. Wrap Up
• 20. Full-Text Search
  • 20.1. Setup
  • 20.1.1. Installing PostgreSQL
  • 20.1.2. Configuring Our Application
  • 20.1.3. pg_search
  • 20.2. Configuring The Models
  • 20.3. Seeding Some Real Data
  • 20.4. The Search Controller
  • 20.5. Pushing Our Changes
  • 20.6. Wrap Up
• 21. Clients Authentication
  • 21.1. Alexandria Custom Auth Scheme
  • 21.2. Identify and Authenticate Clients with API Keys
  • 21.3. Lockdown
  • 21.4. Fixing The Tests
  • 21.5. Preventing Timing Attacks
  • 21.5.1. Fixing the API Key Check
  • 21.6. Generating an API Key
  • 21.7. Pushing our changes
  • 21.8. Wrap Up
• 22. Users
  • 22.1. The User Model
  • 22.2. UserPresenter
  • 22.3. UsersController
  • 22.4. Confirmation Controller
  • 22.5. Password Reset
  • 22.5.1. Step 1 - Initiating The Password Reset Process
  • 22.5.2. Step 2 - Redirecting The User
  • 22.5.3. Step 3 - Updating The Password
  • 22.6. Integration Tests
  • 22.7. Pushing Our Changes
  • 22.8. Wrap Up
• 23. User Authentication & Authorization
  • 23.1. Implementing Access Tokens
  • 23.2. Full Lockdown
  • 23.3. AccessTokensController
  • 23.3.1. The create Action
  • 23.3.2. The destroy Action
  • 23.3.3. Updating Our Controllers
  • 23.3.4. Fixing The Tests
  • 23.4. Authorizing Users
  • 23.4.1. Updating Controllers
  • 23.4.2. Fixing The Tests
  • 23.5. Testing Our Policies
  • 23.6. Adding Some Integration Tests
  • 23.7. Exercises
  • 23.8. Pushing Our Changes
  • 23.9. Wrap Up
• 24. Selling Books
  • 24.1. Adding Prices to Books
  • 24.2. Buying Stuff with the Purchase Model
  • 24.2.1. The Purchase Model
  • 24.2.2. The PurchasePresenter Class
  • 24.3. Integrating Stripe
  • 24.3.1. Creating a Stripe Account
  • 24.3.2. Adding Stripe to Alexandria
  • 24.3.3. Installing The VCR Gem
  • 24.3.4. Connecting to Stripe with a Connector
  • 24.3.5. The Purchase Policy
  • 24.3.6. PurchasesController
  • 24.4. Letting The User Download a Book
  • 24.5. Pushing Our Changes
  • 24.6. Wrap Up
• 25. Compression, Caching, CORS, Versioning
  • 25.1. Compression
  • 25.2. Caching
  • 25.2.1. Client
  • 25.2.2. Server
  • 25.3. CORS
  • 25.4. Versioning?
  • 25.5. Pushing Our Changes
  • 25.6. Wrap Up
• 26. Writing Documentation
  • 26.1. 10 rules for great documentation
  • 26.2. A Few Documentation Tools
  • 26.2.1. Manual
  • 26.2.2. Automated
  • 26.3. Wrap Up
• 27. Deployment
  • 28.1. Deploying to Heroku
  • 28.1.1. Creating an Account
  • 28.1.2. Adding a New Application
  • 28.1.3. Setting Up Alexandria
  • 28.2. Continuous Integration Setup
  • 28.2.1. Preparing
  • 28.2.2. Testing and Deploying Through CircleCI
  • 28.3. Wrap Up
• 28. Second Module Conclusion
  • 28.1. What Did You Learn?
  • 28.2. Conclusion
• 29. REST
  • 29.1. Module Introduction
  • 29.2. “RESTful” is A Buzzword
  • 29.3. Understanding REST
  • 29.4. Exploring The REST Constraints
  • 29.4.1. Client-Server
  • 29.4.2. Stateless
  • 29.4.3. Cache
  • 29.4.4. Uniform Interface
  • 29.4.5. Layered System
  • 29.4.6. Code-On-Demand (Optional)
  • 29.5. Most So-called “RESTful” APIs Are Not Actuallly RESTful
  • 29.6. Richardson Maturity Model
  • 29.7. Wrap Up
• 30. Alexandria and The REST Constraints
  • 30.1. Why Didn’t We Build Alexandria as a RESTful API?
  • 30.2. REST Constraints Compliance
  • 30.2.1. Client-Server
  • 30.2.2. Stateless
  • 30.2.3. Cache
  • 30.2.4. Uniform Interface
  • 30.2.5. Layered System
  • 30.2.6. Code-On-Demand (Optional)
  • 30.3. Using a Custom Media Type
  • 30.3.1. Checking Out A New Branch
  • 30.3.2. Serializing Our Representations
  • 30.3.3. Understanding The Data Sent by Clients
  • 30.4. Going Hypermedia
  • 30.5. Pushing our changes
  • 30.6. Wrap Up
• 31. Exploring More Hypermedia Formats
  • 31.1. Why Use Standard or Specifications for Your Representations?
  • 31.2. A Few Hypermedia Formats
  • 31.2.1. JSON-LD (Standard)
  • 31.2.2. Hydra (Specification)
  • 31.2.3. Collection+JSON (Standard)
  • 31.2.4. HAL (Internet Draft)
  • 31.2.5. SIREN (Specification)
  • 31.2.6. JSON-API (Specification)
  • 31.3. Wrap Up
• 32. Third Module Conclusion
  • 32.1. What Did You Learn?
  • 32.2. Wrap Up
• 33. Conclusion: The Future of Web APIs
  • 33.1. Acknowledgements