RESTful API Design Patterns and Best Practices

【实例截图】

【核心代码】

Table of Contents
Preface 1
Chapter 1: Introduction to the Basics of RESTful Architecture 7
Technical requirements 8
Evolution of web technologies 8
Learning about Web 3.0 9
Learning about web service architecture 11
Discussing the web API 12
Learning about service-oriented architecture 13
Learning about resource-oriented architecture 14
Resource-oriented design 14
The benefits of ROA 16
Beginning with REST 17
REST architecture style constraints 18
Beginning with client-server 19
The client in client-server architecture 20
The service in client-server architecture 20
Understanding statelessness 20
Advantages and disadvantages of statelessness 22
Caching constraint in REST 23
Benefits of caching 24
Understanding the uniform interface 25
Identification of resources 25
Manipulation of resources 26
Self-descriptive messages 27
Hypermedia as the Engine of Application State 29
Layered systems 32
Code on demand 34
RESTful service mandates 35
Architectural goals of REST 36
Summary 37
Chapter 2: Design Strategy, Guidelines, and Best Practices 38
Technical requirements 38
Learning about REST API and its importance 39
Goals of RESTful API design 41
Affordance 41
Loosely coupled 42
Leverage web architecture 42
API designer roles and responsibilities 43
API design best practices 43
API design principles 45
Table of Contents
[ ii ]
Ubiquitous web standards 46
Flexibility 47
Granularity 48
Optimized APIs 50
Functionality 51
Learning about unusual circumstances 52
Community standardization 53
API playgrounds 53
RESTful API design rules 54
Learning about Uniform Resource Identifiers 54
URI formats 55
REST API URI authority 56
Resource modelling 56
Resource archetypes 57
URI path 58
URI query 59
HTTP interactions 59
Request methods 59
Response status codes 60
Metadata design 62
HTTP headers 63
Media types and media type design rules 65
Representations 66
Message body format 67
Hypermedia representation 67
Media type representation 68
Errors representation 68
Client concerns 69
Versioning 69
Security 70
Response representation composition 70
Processing hypermedia 71
JavaScript clients 71
Summary 72
Further reading 72
Chapter 3: Essential RESTful API Patterns 73
Technical requirements 74
Beginning with the installations 74
Beginning with RESTful API patterns – part I 77
Statelessness 78
Content negotiation 80
Content negotiation with HTTP headers 81
URI templates 85
Design for intent 87
Pagination 89
Discoverability 91
Table of Contents
[ iii ]
Error and exception logging 94
Unicode 96
Summary 98
Chapter 4: Advanced RESTful API Patterns 99
Technical requirements 100
RESTful API advanced patterns 100
Versioning 100
Versioning through the URI path 101
Versioning through query parameters 102
Versioning through custom headers 103
Versioning through content-negotiation 105
Authorization 106
Authorization with the default key 107
Authorization with credentials 109
Uniform contract 112
Entity endpoints 112
Endpoint redirection 114
Idempotent 115
Bulk operation 116
Circuit breaker 118
Combining the circuit pattern and the retry pattern 123
API facade 123
Backend for frontend 125
Summary 127
Further reading 127
Chapter 5: Microservice API Gateways 128
Technical requirements 128
About microservice architecture 129
The prominent infrastructure modules in microservice-centric
applications 130
Service registry 131
Service discovery 132
Composition/orchestration 133
Transformation 134
Monitoring 135
Load balancing and scaling 136
High availability and failover 138
HA and failover guidelines 138
Governance 139
About API gateway solutions 139
API gateways for microservice-centric applications 140
The issues with microservice API gateways 143
Security features of API gateways 144
Prominent API gateway solutions 147
Table of Contents
[ iv ]
Service mesh versus API gateway 151
Summary 153
Chapter 6: RESTful Services API Testing and Security 154
An overview of software testing 155
RESTful APIs and testing 155
Basics of API testing 156
Understanding API testing approaches 156
API testing types 156
Unit tests 157
API validation tests 157
Functional tests 158
UI or end-to-end tests 158
Load testing 158
Runtime error detection tests 159
Monitoring APIs 159
Execution errors 159
Resource leaks 160
Error detection 160
REST API security vulnerabilities 161
Exposing sensitive data 161
Understanding authentication and authentication attacks 162
Understanding authorization and OAuth2 schemes 163
Cross-site scripting 171
Reflected XSS 171
Stored XSS 171
DOM XSS 172
Cross-site request forgery 172
Denial-of-service attack 172
Distributed denial of service 173
Injection attacks 173
Insecure direct object references 174
Missing function-level access control 175
Man-in-the-middle attacks 175
Common types of MITM attacks and protection measures 176
Replay attacks and spoofing 177
Causes of vulnerabilities 178
Poor system configuration 179
Human error 179
Internal and external connectivity 179
Security tests 179
Penetration tests or pen tests 180
Importance of penetration tests 180
Pen testing lifecycle 181
Preparation, planning, and reconnaissance 181
Scanning 182
Gaining access 182
Maintaining access 182
Analysis 182
Pen testing types for API testing 182
White-box penetration testing 183
Table of Contents
[ v ]
Fuzz tests 184
The life cycle of fuzz tests 185
Fuzz testing strategy 185
Mutation-based fuzz tests 185
Generation-based fuzz tests 186
Advantages and disadvantages of fuzz tests 187
Back to API testing 189
API test cases 189
Essential aspects of API test cases and test case preparation 189
API testing challenges 190
Initial setup 190
API schema updates for testing 190
Testing parameter combinations 190
API call sequence 191
Validating parameters 191
Tracking system integration 191
API testing best practices 191
API testing tools 192
CQRS 192
Summary 195
Further reading 196
Chapter 7: RESTful Service Composition for Smart Applications 197
Technical requirements 198
Briefing RESTful microservices 198
Demystifying the MSA style 199
The advantages of microservices 200
The emergence of cloud-native applications 201
The growing ecosystem of IoT device services 202
The changing application ecosystem 202
Tending toward the API-driven world 203
The Representational State Transfer service paradigm 204
API design best practices 205
Learning about service-composition methods 205
Service orchestration and choreography 207
Beginning with service orchestration 208
The shortcomings of service orchestration 209
Applying orchestration-based composition 211
Beginning with service choreography 211
The shortcomings of service choreography 214
Applying choreography-based composition 216
The hybridization of orchestration and choreography 216
Another example of the hybridization of orchestration and choreography 218
Choreography 219
Service choreography using the message broker 219
Service orchestration 220
Service orchestration using BPMN and REST 220
The hybridization – event-driven service orchestration 221
Data management 221
Table of Contents
[ vi ]
Thinking in REST 222
Discarding SQL join 224
Eventual consistency 225
Polyglot persistence 226
Summary 227
Chapter 8: RESTful API Design Tips 228
Technical requirements 229
Beginning with APIs 229
Learning about application programming interfaces 230
APIs have become indispensable 231
Learning about the major types of APIs 232
Describing API platforms 232
Creating API development platforms 232
API-integration platforms 234
Legacy integration 235
API management platforms 236
Demystifying the RESTful services paradigm 238
Characterizing the REST architecture style 239
REST Resource Representation Compression 240
Idempotent REST APIs 241
REST API design considerations 241
Enumerating RESTful API design patterns 242
Media types 243
API security design patterns 247
Whitelist allowable methods 247
Summary 250
Further reading 250
Chapter 9: A More In-depth View of the RESTful Services Paradigm 251
Technical requirements 252
Tending toward the software-defined and software-driven world 252
Software-enabled clouds for the digital intelligence era 253
The IoT applications and services 254
Cloud-enabled applications 255
Cloud-native applications 256
Mobile, handheld, and wearable applications 256
Transactional, operational, and analytical applications 257
Knowledge visualization applications 258
Social applications 258
Scientific and technical applications 259
Centralized and distributed applications 259
Decentralized and intelligent applications with blockchain technology 260
Composite and multi-container applications 260
Event-driven applications 260
High-quality applications 261
Resilient applications 262
The REST paradigm for application modernization and integration 262
Table of Contents
[ vii ]
Application programming interfaces 263
Public APIs for external integration and innovation 264
Private APIs for internal purposes 265
APIs for IoT devices 265
APIs for application integration 266
Describing the RESTful services paradigm 266
REST architectural constraints 268
The advantages of REST 270
Self-descriptive messages 272
SOAP versus REST 276
When to use REST versus SOAP 276
Best practices for REST-based microservices 278
The API-first approach 282
Developing API-first 283
Building services API-first 285
Summary 285
Further reading 285
Chapter 10: Frameworks, Standard Languages, and Toolkits 286
Technical requirements 287
Core features of a framework 287
Spring Boot 287
Core features of Spring 288
Database integration with Spring data 289
Messaging integration 289
Extending Spring with auto-configuration 289
Writing unit tests and integration test cases 290
Benefits of Spring Boot 290
Drawbacks of Spring Boot 290
Beginning about Light 4j 291
Core features of Light 4j 291
Learning about Light Rest 4j 291
Light-code-gen 292
Choosing Light 4j over the rest 292
Spark Framework 293
Core features of Spark Framework 293
Creating an API with fewer lines 293
Benefits of Spark 294
Drawbacks of Spark 295
Dropwizard 295
Overview 295
Core features of Dropwizard 296
Jetty for HTTP 296
Jersey for REST 296
Jackson 296
Metrics 297
Liquibase 297
Table of Contents
[ viii ]
Other noteworthy features 297
Benefits of Dropwizard 298
Drawbacks of Dropwizard 298
Understanding Go framework for the RESTful API 298
An overview 299
Gin-gonic 299
Core features 299
HttpRouter 299
Http2 server push 300
Multi-template 300
Upload files 300
Other noteworthy features 300
Benefits of Gin-Gonic 300
Drawbacks of Gin-Gonic 301
Revel 301
Core features 301
Router 301
Server engine 302
Controllers 302
Handlers 302
Interceptors 302
Filters 302
Cache 303
Other noteworthy features 303
Benefits of Revel 303
Drawbacks of Revel 304
Python RESTful API frameworks 304
Overview of Python 304
Django 304
Django Rest Framework 305
Core features 305
Web-browsable API 305
Authentication 305
Serialization and deserialization 306
Other noteworthy features 306
Benefits of the DRF 306
Drawbacks of the DRF 307
Flask 307
Flask-RESTful 307
Core features of Flask-RESTful 307
Resourceful routing 308
Restful request parsing 308
Output fields 308
Other noteworthy features 309
Benefits of the Flask framework 309
Drawbacks of Flask 309
Frameworks – a table of reference 310
Summary 311
Further reading 312
Table of Contents
[ ix ]
Chapter 11: Legacy Modernization to Microservices-Centric Apps 313
Technical requirements 314
A preview of containers and microservices 314
Introducing the microservices architecture 315
Why legacy modernization? 316
Legacy-to-digital application modernization 317
Accomplishing modernization 318
Approaching legacy application modernization 319
Microservices-centric legacy application modernization 319
Service extraction 321
Service composition 321
Service migration 322
Container-centric legacy application modernization 323
Refactoring and rewriting 324
Modernization technique terms 325
Legacy modernization through microservices 328
The distinctions of microservices 329
The code samples 330
The major hurdles to overcome 330
Modernizing and migrating legacy applications – the role of cloud
environments 332
The need for cloud environments 333
A case study for legacy modernization and migration 334
The combination of microservices and serverless computing speeds up legacy
modernization 335
Summary 337
Other Books You May Enjoy 338
Index 341