Table of Contents

Copyright

Brief Table of Contents

Table of Contents

Foreword

Preface

Acknowledgments

About this Book

About the Cover Illustration

1. Understanding web APIs

Chapter 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

Chapter 2. Working with web APIs

2.1. HTTP basics

2.1.1. HTTP request

2.1.2. HTTP response

2.1.3. HTTP interactions

2.2. The Toppings 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

Chapter 3. API First

3.1. Why choose API First?

3.1.1. APIs as side products

3.1.2. API First model

3.2. Code consistency

3.3. Functional equality

3.4. Increased productivity

3.5. Internal/external access

3.6. Case studies

3.6.1. API as the main product

3.6.2. Mobile First

3.6.3. Refactoring for API First

3.6.4. API First strategic direction

3.7. Summary

Chapter 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

2. Designing web APIs

Chapter 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.1. Expand and include related resources

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

Chapter 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

Chapter 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. Step 4: 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. OpenAPI (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. OpenAPI tools and resources

7.5. Summary

Chapter 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 project management 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

Planning

Standups

Kanban “Swim Lanes”

Retrospective

8.6. Summary

Chapter 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. Noninteractive

9.6. Summary

Index

List of Figures

List of Tables

List of Listings