book

Microservice APIs

by Jose Haro

February 2023

Intermediate to advanced

440 pages

12h 20m

English

Manning Publications

Read now

Unlock full access

prefaceacknowledgmentsabout this bookWho should read this book?How this book is organized: A roadmapAbout the codeliveBook discussion forumOther online resourcesabout the authorabout the cover illustration
1.1 What are microservices?1.1.1 Defining microservices1.1.2 Microservices vs. monoliths1.1.3 Microservices today and how we got here1.2 What are web APIs?1.2.1 What is an API?1.2.2 What is a web API?1.2.3 How do APIs help us drive microservices integrations?1.3 Challenges of microservices architecture1.3.1 Effective service decomposition1.3.2 Microservices integration tests1.3.3 Handling service unavailability1.3.4 Tracing distributed transactions1.3.5 Increased operational complexity and infrastructure overhead1.4 Introducing documentation-driven development1.5 Introducing the CoffeeMesh application1.6 Who this book is for and what you will learnSummary
2.1 Introducing the orders API specification2.2 High-level architecture of the orders application2.3 Implementing the API endpoints2.4 Implementing data validation models with pydantic2.5 Validating request payloads with pydantic2.6 Marshalling and validating response payloads with pydantic2.7 Adding an in-memory list of orders to the APISummary
3.1 Introducing CoffeeMesh3.2 Microservices design principles3.2.1 Database-per-service principle3.2.2 Loose coupling principle3.2.3 Single Responsibility Principle3.3 Service decomposition by business capability3.3.1 Analyzing the business structure of CoffeeMesh3.3.2 Decomposing microservices by business capabilities3.4 Service decomposition by subdomains3.4.1 What is domain-driven design?3.4.2 Applying strategic analysis to CoffeeMesh3.5 Decomposition by business capability vs. decomposition by subdomainSummary

4.1 What is REST?4.2 Architectural constraints of REST applications4.2.1 Separation of concerns: The client-server architecture principle4.2.2 Make it scalable: The statelessness principle4.2.3 Optimize for performance: The cacheability principle4.2.4 Make it simple for the client: The layered system principle4.2.5 Extendable interfaces: The code-on-demand principle4.2.6 Keep it consistent: The uniform interface principle4.3 Hypermedia as the engine of application state4.4 Analyzing the maturity of an API with the Richardson maturity model4.4.1 Level 0: Web APIs à la RPC4.4.2 Level 1: Introducing the concept of resource4.4.3 Level 2: Using HTTP methods and status codes4.4.4 Level 3: API discoverability4.5 Structured resource URLs with HTTP methods4.6 Using HTTP status codes to create expressive HTTP responses4.6.1 What are HTTP status codes?4.6.2 Using HTTP status codes to report client errors in the request4.6.3 Using HTTP status codes to report errors in the server4.7 Designing API payloads4.7.1 What are HTTP payloads, and when do we use them?4.7.2 HTTP payload design patterns4.8 Designing URL query parametersSummary
5.1 Using JSON Schema to model data5.2 Anatomy of an OpenAPI specification5.3 Documenting the API endpoints5.4 Documenting URL query parameters5.5 Documenting request payloads5.6 Refactoring schema definitions to avoid repetition5.7 Documenting API responses5.8 Creating generic responses5.9 Defining the authentication scheme of the APISummary
6.1 Overview of the orders API6.2 URL query parameters for the orders API6.3 Validating payloads with unknown fields6.4 Overriding FastAPI’s dynamically generated specification6.5 Overview of the kitchen API6.6 Introducing flask-smorest6.7 Initializing the web application for the API6.8 Implementing the API endpoints6.9 Implementing payload validation models with marshmallow6.10 Validating URL query parameters6.11 Validating data before serializing the response6.12 Implementing an in-memory list of schedules6.13 Overriding flask-smorest’s dynamically generated API specificationSummary
7.1 Hexagonal architectures for microservices7.2 Setting up the environment and the project structure7.3 Implementing the database models7.4 Implementing the repository pattern for data access7.4.1 The case for the repository pattern: What is it, and why is it useful?7.4.2 Implementing the repository pattern7.5 Implementing the business layer7.6 Implementing the unit of work pattern7.7 Integrating the API layer and the service layerSummary
8.1 Introducing GraphQL8.2 Introducing the products API8.3 Introducing GraphQL’s type system8.3.1 Creating property definitions with scalars8.3.2 Modeling resources with object types8.3.3 Creating custom scalars8.4 Representing collections of items with lists8.5 Think graphs: Building meaningful connections between object types8.5.1 Connecting types through edge properties8.5.2 Creating connections with through types8.6 Combining different types through unions and interfaces8.7 Constraining property values with enumerations8.8 Defining queries to serve data from the API8.9 Altering the state of the server with mutationsSummary
9.1 Running a GraphQL mock server9.2 Introducing GraphQL queries9.2.1 Running simple queries9.2.2 Running queries with parameters9.2.3 Understanding query errors9.3 Using fragments in queries9.4 Running queries with input parameters9.5 Navigating the API graph9.6 Running multiple queries and query aliasing9.6.1 Running multiple queries in the same request9.6.2 Aliasing our queries9.7 Running GraphQL mutations9.8 Running parameterized queries and mutations9.9 Demystifying GraphQL queries9.10 Calling a GraphQL API with Python codeSummary
10.1 Analyzing the API requirements10.2 Introducing the tech stack10.3 Introducing Ariadne10.4 Implementing the products API10.4.1 Laying out the project structure10.4.2 Creating an entry point for the GraphQL server10.4.3 Implementing query resolvers10.4.4 Implementing type resolvers10.4.5 Handling query parameters10.4.6 Implementing mutation resolvers10.4.7 Building resolvers for custom scalar types10.4.8 Implementing field resolversSummary
11.1 Setting up the environment for this chapter11.2 Understanding authentication and authorization protocols11.2.1 Understanding Open Authorization11.2.2 Understanding OpenID Connect11.3 Working with JSON Web Tokens11.3.1 Understanding the JWT header11.3.2 Understanding JWT claims11.3.3 Producing JWTs11.3.4 Inspecting JWTs11.3.5 Validating JWTs11.4 Adding authorization to the API server11.4.1 Creating an authorization module11.4.2 Creating an authorization middleware11.4.3 Adding CORS middleware11.5 Authorizing resource access11.5.1 Updating the database to link users and orders11.5.2 Restricting user access to their own resourcesSummary
12.1 Setting up the environment for API testing12.2 Testing REST APIs with Dredd12.2.1 What is Dredd?12.2.2 Installing and running Dredd’s default test suite12.2.3 Customizing Dredd’s test suite with hooks12.2.4 Using Dredd in your API testing strategy12.3 Introduction to property-based testing12.3.1 What is property-based testing?12.3.2 The traditional approach to API testing12.3.3 Property-based testing with Hypothesis12.3.4 Using Hypothesis to test a REST API endpoint12.4 Testing REST APIs with Schemathesis12.4.1 Running Schemathesis’s default test suite12.4.2 Using links to enhance Schemathesis’ test suite12.5 Testing GraphQL APIs12.5.1 Testing GraphQL APIs with Schemathesis12.6 Designing your API testing strategySummary
13.1 Setting up the environment for this chapter13.2 Dockerizing a microservice13.3 Running applications with Docker Compose13.4 Publishing Docker builds to a container registrySummary
14.1 Setting up the environment for this chapter14.2 How Kubernetes works: The “CliffsNotes” version14.3 Creating a Kubernetes cluster with EKS14.4 Using IAM roles for Kubernetes service accounts14.5 Deploying a Kubernetes load balancer14.6 Deploying microservices to the Kubernetes cluster14.6.1 Creating a deployment object14.6.2 Creating a service object14.6.3 Exposing services with ingress objects14.7 Setting up a serverless database with AWS Aurora14.7.1 Creating an Aurora Serverless database14.7.2 Managing secrets in Kubernetes14.7.3 Running the database migrations and connecting our service to the database14.8 Updating the OpenAPI specification with the ALB’s hostname14.9 Deleting the Kubernetes clusterSummary
A.1 The dawn of APIs: RPC, XML-RPC, and JSON-RPCA.2 SOAP and the emergence of API standardsA.3 RPC strikes again: Fast exchanges over gRPCA.4 HTTP-native APIs with RESTA.5 Granular queries with GraphQL
B.1 Versioning strategies for evolving APIsB.2 Managing the life cycle of your APIs
C.1 Using an identity as a service providerC.2 Using the PKCE authorization flowC.3 Using the client credentials flowC.4 Authorizing requests in the Swagger UI

Overview

Strategies, best practices, and patterns that will help you design resilient microservices architecture and streamline your API integrations.

In Microservice APIs, you’ll discover:

Service decomposition strategies for microservices
Documentation-driven development for APIs
Best practices for designing REST and GraphQL APIs
Documenting REST APIs with the OpenAPI specification (formerly Swagger)
Documenting GraphQL APIs using the Schema Definition Language
Building microservices APIs with Flask, FastAPI, Ariadne, and other frameworks
Service implementation patterns for loosely coupled services
Property-based testing to validate your APIs, and using automated API testing frameworks like schemathesis and Dredd
Adding authentication and authorization to your microservice APIs using OAuth and OpenID Connect (OIDC)
Deploying and operating microservices in AWS with Docker and Kubernetes

Microservice APIs teaches you practical techniques for designing robust microservices with APIs that are easy to understand, consume, and maintain. You’ll benefit from author José Haro Peralta’s years of experience experimenting with microservices architecture, dodging pitfalls and learning from mistakes he’s made. Inside you’ll find strategies for delivering successful API integrations, implementing services with clear boundaries, managing cloud deployments, and handling microservices security. Written in a framework-agnostic manner, its universal principles can easily be applied to your favorite stack and toolset.

About the Technology
Clean, clear APIs are essential to the success of microservice applications. Well-designed APIs enable reliable integrations between services and help simplify maintenance, scaling, and redesigns. This book teaches you the patterns, protocols, and strategies you need to design, build, and deploy effective REST and GraphQL microservices APIs.

About the Book
Microservice APIs gathers proven techniques for creating and building easy-to-consume APIs for microservices applications. Rich with proven advice and Python-based examples, this practical book focuses on implementation over philosophy. You’ll learn how to build robust microservice APIs, test and protect them, and deploy them to the cloud following principles and patterns that work in any language.

What's Inside

Service decomposition strategies for microservices
Best practices for designing and building REST and GraphQL APIs
Service implementation patterns for loosely coupled components
API authorization with OAuth and OIDC
Deployments with AWS and Kubernetes

About the Reader
For developers familiar with the basics of web development. Examples are in Python.

About the Author
José Haro Peralta is a consultant, author, and instructor. He’s also the founder of microapis.io.

Quotes
An insightful guide for creating REST and GraphQL APIs, with neat examples using FastAPI and Flask. The service implementation patterns chapter is a must-read for every developer.
- William Jamir Silva, Adjust

A perfect introduction to microservice web APIs in Python.
- Stuart Woodward, CEO, Hanamaru

A well-designed API makes all the difference in the success of your next project. This book equips you with the knowledge and the skills you need. Excellent!
- Alain Lompo, ISO-Gruppe

Excellent coverage with practical examples.
- Sambasiva Andaluri, IBM