Designing Great Web APIs by Higginbotham, James -- Read -- Imperial Library of Trantor

Index

1. The Business of APIs

What Are APIs? The Rise of the API Economy

Reason #1 – Higher Demand Reason #2 – Simplicity Reason #3 –Lower Cost Reason #4 – New Business Models

Business Advantages of Web APIs

Consuming APIs from Others Exposing APIs to Other Developers

Web API Development versus Traditional Software

2. Guidelines for Designing a Great API

#1 - Treat Your API as a Product #2 – Take an Outside-In Design Approach

Organizational structure leaks Database structure leaks

#3 – Write Great Documentation

Format Completeness Interactive

#4 – Have an Intuitive, Consistent Design

Consistent naming Consistent resource URLs Consistent payload formats Beyond data: Supporting API-based workflows

#5 – Design for Security at the Start

Authentication Authorization Data leakage Always use TLS Designing with security is important

#6 – Share Great Code Examples

Milestone 1: First success Milestone 2: Workflow support Milestone 3: Production-ready integration

#7 – Provide Helper Libraries

3. The Design-First API Process

User Interface Wireframes to Drive API Design API Modeling

Step 1: Identify the Participants Step 2: Identify the Activities Step 3: Separate the Activities into Steps Step 4: Identify the Resources and Candidate APIs Step 5: Validate the API Model

Next Step: Detailed API Design

4. API Design Details

An HTTP Primer

HTTP Is Request/Response Uniform Resource Locators (URLs) HTTP Verbs HTTP Requests HTTP Responses

Building Your Resource Ontology Defining URLs Through Relationships Mapping Resource Lifecycles to HTTP Verbs Mapping Response Codes Validating Design Through Documentation and Prototyping Putting It All Together