RESTful API Design APIs your consumers will love

Transcription

1 RESTful API Design APIs your consumers will love Matthias Biehl

2 RESTful API Design Copyright 2016 by Matthias Biehl All rights reserved, including the right to reproduce this book or portions thereof in any form whatsoever. First edition: August 2016 Biehl, Matthias API-University Press Volume 3 of the API-University Series. Includes illustrations, bibliographical references and index. ISBN-13: ISBN-10: API-University Press info@api-university.com

3 Contents 1. Introduction What is an API? Why APIs? How are APIs used? What is API Design? What is the difference between API Design and API Architecture? Why is API Design Important? Why should I build RESTful APIs? Why do I need OpenAPI, Swagger or RAML? How to put API Design into Practice? Consumer-Oriented API Design: APIs are Products Why should APIs be Consumer-Oriented? What is a Consumer-Oriented API? How to build Consumer-Oriented APIs? Identify the API Consumers Engage with API Consumers Learn about the Solution Architecture of Consumers API Design and Development Approach Foundations Consumer-Oriented Design Approach Inside-out Approach Outside-in Approach Contract First Design Approach

4 Agile Design Approach Simulation-based Design Simulation of Backends Simulation of the API Conclusion Design Approach Overview Phase 1: Domain Analysis Verification of Phase 1: Simulation & Demo App Phase 2: Architectural Design Verification of Phase 2: Simulation & Demo App Phase 3: Prototyping Validation of Phase 3: Acceptance Tests with Pilot Consumers Phase 4: Implementation for Production Verification of Phase 4: Acceptance Tests with Pilot Consumers Phase 5: Publish Verification of Phase 5: Study Metrics, Reports and Logs Maintenance Discussion Hand-over Points Pre-Work vs. Actual Work Summary API Design with API Description Languages What are API Description Languages? Usage Communication and Documentation Design Repository Contract Negotiation

5 API Implementation Client Implementation Discovery Simulation Language Features Limitations Summary API Architectural Design Decisions Requirements for APIs Responsibilities of APIs Gathering Data Structuring and Formatting Data Delivering Data Securing and Protecting Desirable Properties of APIs Consumer-Centric Self-Explanatory, Intuitive and Predictable Explorable and Discoverable Well-Documented Atomic Forgiving and Forward Compatible Secure and Compliant Performant, Scalable and Available Conforming to Standards Interoperable Reusable Backward Compatible Summary Architectural Patterns Client Server Patterns Stateful Server Pattern Stateless Server Pattern

6 Facade Pattern Proxy Pattern Architectural Styles REST Style HATEOAS Style RPC Style How does RPC work? JSON-RPC XML-RPC SOAP Style Streaming Style Architectural Trade-offs RPC in Comparison to REST HATEOAS in Comparison to REST SOAP in Comparison to REST Introduction to REST HTTP REST Concepts Resource API Representation Uniform Resource Interface REST Constraints State in REST Application State Resource State Advantages of REST HATEOAS Style HATEOAS Concepts HATEOAS Constraints Advantages of HATEOAS

7 7. API Frontend Design Decisions Resources What is a Resource? Instance Resources Collection Resources Controller Resources Resource Ordering Root Resource Sub Resource Resource Granularity Resource Relations Option 1: Resource Ordering Option 2: IDs and Separate Root Resources Option 3: Links and Separate Root Resources Option 4: Embedded Resources Links Relative URIs vs. Absolute URIs Expressing URI Parameters Best Practices for Resource Design No Redundancy No Internal Data No Composite Resources URI Design Introduction Design Recommendations URI Template Stable URIs Nesting Depth Maximum Length of URIs URLs of Collections Resources. 112

8 7.3. Representations Content Negotiation API-side Content Negotiation Mechanism Client-side Content Negotiation Mechanism Negotiating Media-Types Negotiating Language Negotiating Character Encoding Negotiating Content Encoding Standard Data Formats Date and Time UUID Binary Data JSON JSON Schema: Defining the Structure of your JSON Objects Conversion between JSON and XML Common JSON Anti Patterns JSONP Parameters Use of Parameter Types Filter- and Sorting Locators Projections Projection on Collection Resources Projection on Instance Resources Metadata Parameter Types Path Parameters Query Parameters Form Parameters Header Parameters

9 7.5. Methods Use of HTTP Methods Retrieve a Resource Create a new Resource Update a Resource Delete a Resource Check Existence of a Resource Determine the Supported Methods Test the Request Meaning of HTTP Methods GET POST PUT DELETE PATCH HEAD OPTIONS TRACE CONNECT Non-Standard HTTP Methods Properties of HTTP Methods Safe Idempotent Status Codes Overview of HTTP Status Codes Redirection Error Handling Client Errors Server Errors Error Message Input and Output Validation Input Validation Output Validation Consistent Names

10 7.9. Integratation Cross-Origin Resource Sharing (CORS) Browser Explorability Robustness OpenAPI/Swagger for API Frontend Design Introduction Root Element Resources Schema Parameters Reusable Elements Security Security Definition Security Binding RAML for API Frontend Design Introduction Root Element Schema Parameters Path Parameters Query Parameters Form Parameters Header Parameters Reusable Elements External Elements: Inclusion of Files Internal Elements: Definition of Resource Types and Traits Internal Elements: Usage of Resource Types and Traits Security

11 10.API Backend Design Decisions Backends Transformations Transformation Source and Target Request Transformation Response Transformation Transformation Tasks Data Structure Transformation Representation Transformation Conversion between JSON and XML Security Mediation Transformation Tools Dealing with Backend Errors Logging Require a Transaction ID / Request ID / Tracking ID Non-Functional Properties of APIs Security The Appropriate Level of Security Security Concerns Authentication Authorization Delegation Identity Attacks Integrity of API Input and Output Security Mechanisms API Keys HTTP Basic HTTP Digest OAuth OpenID Connect and JWT

12 Access Restrictions by IP, Location and Time X.509 Transport Layer Security (TLS) Visibility Levels Validation Best Practice Ensuring Confidentiality and Integrity of Information in URIs Treat All APIs as Public APIs Known Vulnerabilities and Known Attack Patterns Protect All APIs with OAuth by Default CORS Performance Caching API-Side Caching Client-Side HTTP Caching Reading Cached Data with Conditional GET Writing Cached Data with Conditional POST, PUT and DELETE Writing Cached Data with Conditional PUT and DELETE Writing Cached Data with Conditional POST Cache Expiration Cache Control Header Parameters for Cache Control Cacheable Responses Pagination Use of Traffic Shaping

13 Enable Content Compression Remove Whitespace from Responses Availability Traffic Shaping Use Case: Protect API Platform Use Case: Protect Backends Use Case: Limit User Access Rate Limitation Implement Rate Limitation Optimistic Rate Limitation Spike Limitation and Spike Smoothing Quota Caching Evolution and Versioning The Evolution Challenge Analysis of Evolution Backward Compatible Changes Forward Compatible Changes Incompatible Changes Conclusion of the Analysis Anticipating and Avoiding Evolution Evolution from a Methodological Perspective Coping with Evolution - Versioning HATEOAS Versioning via Links Realize API Versioning in Accept Header Realize API Versioning as URI Path Parameter Realize API Versioning in a Custom HTTP Header Realize API Versioning as Query Parameter

14 Realize API Versioning as a new Subdomain Supporting Multiple Versions Simultaneously Anti-Patterns Using Token Attributes to Store Application State Using Resources to Store Application State API Client Design Designing the Solution Functionality in the Client or in the API? Use an existing API or build a new API? How to choose a third party API? Step 1: Find the API Step 2: Learn about the API Step 3: Test the API Step 4: Use the API Discovering APIs Consumer Discovery Automatic Discovery Calling APIs Implementing the API Call Content Negotiation Permissive Processing Dealing with Errors A. Appendix 239 A.1. Feedback A.2. About the Author A.3. Other Products by the Author A.3.1. Online Course on RESTful API Design. 240 A.3.2. Book on API Architecture

15 A.3.3. Online Course on API Security with OAuth A.3.4. Book on API Security with OAuth B. HTTP Methods 245 C. HTTP Headers 247 D. HTTP Status Codes 253