Irresistible APIs
Designing web APIs that developers will love
Kirsten L. Hunter
Foreword by Adrian Cockcroft
  • September 2016
  • ISBN 9781617292552
  • 232 pages
  • printed in black & white

Explains how to build well-engineered APIs.

From the Foreword by Adrian Cockcroft, Battery Ventures

Irresistible APIs provides step-by-step guidance for designing APIs that reflect an application's core business value, delight the developers who use them, and will stand the test of time. In it, business product managers and developers learn how to treat an API as a first-class product.

Table of Contents detailed table of contents

Part 1: Understanding Web APIs

1. What Makes an API Irresistible?

1.1. Integrating Social APIs into Web Content

1.2. What is a Web API?

1.2.1. Do You Need an API?

1.2.2. Choosing REST APIs

1.2.3. JSON

1.3. Developer Experience

1.3.1. Versioning

1.3.2. Marketing to Developers

1.4. Common Pitfalls of Organic APIs

1.4.1. Lack of Vision

1.4.2. Prioritizing the Developer Experience

1.4.3. Bad API Design

1.5. API Creation Process

1.5.1. Determine your Business Value

1.5.2. Choose your Metrics

1.5.3. Define your Use Cases

1.5.4. Design your API

1.5.5. Industry Standards

1.5.6. Design Driven Development

1.5.7. Support your Developers

1.6. Summary

2. Working with Web APIs

2.1. HTTP Basics

2.2. The Topping API

2.3. Designing the API

2.4. Using a web API

2.4.1. Browser

2.4.2. Command Line (Curl)

2.4.3. HTTP Sniffers

2.5. Interaction Between the API and Client

2.6. Install Your Own API and Front End

2.6.1. Installing the System via Docker

2.6.2. Installing the System via Git

2.6.3. Exploring the Code

2.7. Summary

3. API First

3.1. What is API First?

3.1.1. APIs as a Side Product

3.1.2. API First Model

3.2. Code Consistency

3.3. Feature Equality

3.4. Increased Velocity

3.5. Internal/External Access

3.6. Case Studies

3.6.1. API as Your Product

3.6.2. Mobile First

3.6.3. Refactoring for API First

3.6.4. API First Strategic Direction

3.7. Summary

4. Web Services Explained

4.1. HTTP Fundamentals

4.1.1. Addressability

4.1.2. Status Codes

4.1.3. Body

4.1.4. HTTP Verbs

4.1.5. Headers

4.1.6. Parameters

4.1.7. HTTP Overview — Summary

4.2. REST Web Services Explained

4.3. Exploring your API by Inspecting HTTP Traffic

4.3.1. Setting up Chrome for HTTP Inspection

4.4. Web Services Best Practices

4.4.1. Using the Right Status Codes

4.4.2. Methods and Idempotency

4.4.3. Nouns Vs. Verbs

4.5. Troubleshooting Web API Interactions

4.5.1. Tools for API Inspection

4.5.2. Error Handling

4.5.3. Defensive Coding

4.6. Summary

Part 2: Designing Web APIs

5. Guiding Principles for API Design

5.1. Don't surprise your users

5.1.1. Flickr API Example

5.1.2. Don’t Make me Think

5.2. Focus on Use Cases

5.2.1. Use Case: Mobile

5.2.2. Use Case: Application Integration

5.3. Copy Successful APIs

5.4. REST is Not Always Best

5.4.2. Create a Query Language

5.4.3. Create a Comprehensive Data Transfer Scheme

5.4.4. Create a Separate Batching System

5.4.5. RESTful Decisions

5.5. Focus on the Developer Experience

5.5.1. Communication and Consistency Are Critical

5.5.2. Documentation Should Tell a Story

5.6. Summary

6. Defining the Value for your API

6.1. Business Goals

6.1.1. Monetization

6.1.2. Usage

6.1.3. Partner Retention

6.1.4. Market Dominance

6.2. Metrics

6.2.1. Poor Metrics

6.2.2. Monetization

6.2.3. Usage

6.2.4. Partner Retention

6.2.5. Market Dominance

6.3. Use Cases

6.3.1. Mobile

6.3.2. Monetization

6.3.3. Usage

6.3.4. Customer/Partner Retention

6.4. Summary

7. Creating Your Schema Model

7.1. What is a Schema Model?

7.2. What does the API need to do?

7.2.1. Top-Level Resources

7.2.2. API Resource Methods

7.3. RAML

7.3.1. Getting Started

7.3.2. Step 1: Adding Resources

7.3.3. Step 2: Adding the methods

7.3.4. Step 3: Query Parameters

7.3.5. Adding Mock Data

7.3.6. Step 5: Adding Mock Data - GET

7.3.7. Step 6: Adding Mock Data - POST

7.3.8. Step 7: GET response format

7.3.9. Step 8: PUT response format

7.3.10. Step 9: DELETE

7.3.11. Step 10: searching

7.3.12. Support tools for RAML

7.4. Open API — Previously Swagger

7.4.1. Information about your API

7.4.2. Step 1: API Top-Level Resource Methods - GET

7.4.3. Step 2: API Top-Level Resource Methods - POST

7.4.4. Step 3: API Subresource Methods - GET, PUT, DELETE

7.4.5. Open API Tools and Resources

7.5. Summary

8. Design-Driven Development

8.1. Development Strategies for your API

8.1.1. Waterfall Development

8.1.2. Agile/Test-first Development

8.1.3. Behavior Driven Development

8.1.4. Design Driven Development

8.1.5. Code-First Development

8.1.6. Why does it Matter?

8.2. Project Management for APIs

8.2.1. Functional Specification

8.2.2. Schema Model

8.3. Road Testing your API

8.3.1. Creating a mock server API

8.3.2. Acceptance Tests and Use Cases

8.4. Planning Development

8.5. Development Sprints

8.6. Summary

9. Empowering Your Developers

9.1. Pillars of Developer Experience

9.2. Communicating with your Developers

9.2.1. Failures of Communication

9.2.2. Strong Communication

9.2.3. Advantages to Strong and Consistent Communication

9.3. Documenting your API

9.3.1. Reference Documentation

9.3.2. Workflows

9.3.3. Tutorials

9.4. Building Blocks

9.4.1. Sample Code

9.4.2. Reference Applications

9.4.3. Tools and Techniques

9.5. Developer Support

9.5.1. Interactive

9.5.2. Non-Interactive

9.6. Summary

About the Technology

It takes a village to deliver an irresistible web API. Business stakeholders look for an API that works side-by-side with the main product to enhance the experience for customers. Project managers require easy integration with other products or ways for customers to interact with your system. And, developers need APIs to consistently interoperate with external systems. The trick is getting the whole village together. This book shows you how.

About the book

Irresistible APIs presents a process to create APIs that succeed for all members of the team. In it, you’ll learn how to capture an application’s core business value and extend it with an API that will delight the developers who use it. Thinking about APIs from the business point of view, while also considering the end-user experience, encourages you to explore both sides of the design process and learn some successful biz-to-dev communication patterns. Along the way, you’ll start to view your APIs as part of your product’s core value instead of just an add-on.

What's inside

  • Design-driven development
  • Developing meaningful use cases
  • API guiding principles
  • How to recognize successful APIs

About the reader

Written for all members of an API design team, regardless of technical level.

About the author

Kirsten Hunter is an API evangelist who helps developers and business stakeholders understand, design, and deliver amazing APIs.


Buy
combo $44,99 pBook + eBook
eBook $35,99 pdf + ePub + kindle

FREE domestic shipping on three or more pBooks

An excellent and well-thought-out approach for designing the APIs that your business needs and your developers deserve.

Stephen Byrne, Dell

A future is emerging where our APIs are our public face as much as our website, office space, or sales staff. This book points the way.

Joel Kotarski, Humana Inc.

The definitive guide to both the "why" and the "how" of building beautiful APIs.

Andrew Meredith, Quantum Metric