Microservice APIs

Microservice APIs

by Jose Haro
Released February 2023
Publisher(s): Manning Publications
ISBN: 9781617298417

Read it now on the O’Reilly learning platform with a 10-day free trial.

O’Reilly members get unlimited access to books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.

Start your free trial

Book description

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

Table of contents

  1. inside front cover
  2. Microservice APIs
  3. Copyright
  4. dedication
  5. contents
  6. front matter
    1. preface
    2. acknowledgments
    3. about this book
      1. Who should read this book?
      2. How this book is organized: A roadmap
      3. About the code
      4. liveBook discussion forum
      5. Other online resources
    4. about the author
    5. about the cover illustration
  7. Part 1. Introducing Microservice APIs
  8. 1 What are microservice APIs?
    1. 1.1 What are microservices?
      1. 1.1.1 Defining microservices
      2. 1.1.2 Microservices vs. monoliths
      3. 1.1.3 Microservices today and how we got here
    2. 1.2 What are web APIs?
      1. 1.2.1 What is an API?
      2. 1.2.2 What is a web API?
      3. 1.2.3 How do APIs help us drive microservices integrations?
    3. 1.3 Challenges of microservices architecture
      1. 1.3.1 Effective service decomposition
      2. 1.3.2 Microservices integration tests
      3. 1.3.3 Handling service unavailability
      4. 1.3.4 Tracing distributed transactions
      5. 1.3.5 Increased operational complexity and infrastructure overhead
    4. 1.4 Introducing documentation-driven development
    5. 1.5 Introducing the CoffeeMesh application
    6. 1.6 Who this book is for and what you will learn
    7. Summary
  9. 2 A basic API implementation
    1. 2.1 Introducing the orders API specification
    2. 2.2 High-level architecture of the orders application
    3. 2.3 Implementing the API endpoints
    4. 2.4 Implementing data validation models with pydantic
    5. 2.5 Validating request payloads with pydantic
    6. 2.6 Marshalling and validating response payloads with pydantic
    7. 2.7 Adding an in-memory list of orders to the API
    8. Summary
  10. 3 Designing microservices
    1. 3.1 Introducing CoffeeMesh
    2. 3.2 Microservices design principles
      1. 3.2.1 Database-per-service principle
      2. 3.2.2 Loose coupling principle
      3. 3.2.3 Single Responsibility Principle
    3. 3.3 Service decomposition by business capability
      1. 3.3.1 Analyzing the business structure of CoffeeMesh
      2. 3.3.2 Decomposing microservices by business capabilities
    4. 3.4 Service decomposition by subdomains
      1. 3.4.1 What is domain-driven design?
      2. 3.4.2 Applying strategic analysis to CoffeeMesh
    5. 3.5 Decomposition by business capability vs. decomposition by subdomain
    6. Summary
  11. Part 2. Designing and building REST APIs
  12. 4 Principles of REST API design
    1. 4.1 What is REST?
    2. 4.2 Architectural constraints of REST applications
      1. 4.2.1 Separation of concerns: The client-server architecture principle
      2. 4.2.2 Make it scalable: The statelessness principle
      3. 4.2.3 Optimize for performance: The cacheability principle
      4. 4.2.4 Make it simple for the client: The layered system principle
      5. 4.2.5 Extendable interfaces: The code-on-demand principle
      6. 4.2.6 Keep it consistent: The uniform interface principle
    3. 4.3 Hypermedia as the engine of application state
    4. 4.4 Analyzing the maturity of an API with the Richardson maturity model
      1. 4.4.1 Level 0: Web APIs à la RPC
      2. 4.4.2 Level 1: Introducing the concept of resource
      3. 4.4.3 Level 2: Using HTTP methods and status codes
      4. 4.4.4 Level 3: API discoverability
    5. 4.5 Structured resource URLs with HTTP methods
    6. 4.6 Using HTTP status codes to create expressive HTTP responses
      1. 4.6.1 What are HTTP status codes?
      2. 4.6.2 Using HTTP status codes to report client errors in the request
      3. 4.6.3 Using HTTP status codes to report errors in the server
    7. 4.7 Designing API payloads
      1. 4.7.1 What are HTTP payloads, and when do we use them?
      2. 4.7.2 HTTP payload design patterns
    8. 4.8 Designing URL query parameters
    9. Summary
  13. 5 Documenting REST APIs with OpenAPI
    1. 5.1 Using JSON Schema to model data
    2. 5.2 Anatomy of an OpenAPI specification
    3. 5.3 Documenting the API endpoints
    4. 5.4 Documenting URL query parameters
    5. 5.5 Documenting request payloads
    6. 5.6 Refactoring schema definitions to avoid repetition
    7. 5.7 Documenting API responses
    8. 5.8 Creating generic responses
    9. 5.9 Defining the authentication scheme of the API
    10. Summary
  14. 6 Building REST APIs with Python
    1. 6.1 Overview of the orders API
    2. 6.2 URL query parameters for the orders API
    3. 6.3 Validating payloads with unknown fields
    4. 6.4 Overriding FastAPI’s dynamically generated specification
    5. 6.5 Overview of the kitchen API
    6. 6.6 Introducing flask-smorest
    7. 6.7 Initializing the web application for the API
    8. 6.8 Implementing the API endpoints
    9. 6.9 Implementing payload validation models with marshmallow
    10. 6.10 Validating URL query parameters
    11. 6.11 Validating data before serializing the response
    12. 6.12 Implementing an in-memory list of schedules
    13. 6.13 Overriding flask-smorest’s dynamically generated API specification
    14. Summary
  15. 7 Service implementation patterns for microservices
    1. 7.1 Hexagonal architectures for microservices
    2. 7.2 Setting up the environment and the project structure
    3. 7.3 Implementing the database models
    4. 7.4 Implementing the repository pattern for data access
      1. 7.4.1 The case for the repository pattern: What is it, and why is it useful?
      2. 7.4.2 Implementing the repository pattern
    5. 7.5 Implementing the business layer
    6. 7.6 Implementing the unit of work pattern
    7. 7.7 Integrating the API layer and the service layer
    8. Summary
  16. Part 3. Designing and building GraphQL APIs
  17. 8 Designing GraphQL APIs
    1. 8.1 Introducing GraphQL
    2. 8.2 Introducing the products API
    3. 8.3 Introducing GraphQL’s type system
      1. 8.3.1 Creating property definitions with scalars
      2. 8.3.2 Modeling resources with object types
      3. 8.3.3 Creating custom scalars
    4. 8.4 Representing collections of items with lists
    5. 8.5 Think graphs: Building meaningful connections between object types
      1. 8.5.1 Connecting types through edge properties
      2. 8.5.2 Creating connections with through types
    6. 8.6 Combining different types through unions and interfaces
    7. 8.7 Constraining property values with enumerations
    8. 8.8 Defining queries to serve data from the API
    9. 8.9 Altering the state of the server with mutations
    10. Summary
  18. 9 Consuming GraphQL APIs
    1. 9.1 Running a GraphQL mock server
    2. 9.2 Introducing GraphQL queries
      1. 9.2.1 Running simple queries
      2. 9.2.2 Running queries with parameters
      3. 9.2.3 Understanding query errors
    3. 9.3 Using fragments in queries
    4. 9.4 Running queries with input parameters
    5. 9.5 Navigating the API graph
    6. 9.6 Running multiple queries and query aliasing
      1. 9.6.1 Running multiple queries in the same request
      2. 9.6.2 Aliasing our queries
    7. 9.7 Running GraphQL mutations
    8. 9.8 Running parameterized queries and mutations
    9. 9.9 Demystifying GraphQL queries
    10. 9.10 Calling a GraphQL API with Python code
    11. Summary
  19. 10 Building GraphQL APIs with Python
    1. 10.1 Analyzing the API requirements
    2. 10.2 Introducing the tech stack
    3. 10.3 Introducing Ariadne
    4. 10.4 Implementing the products API
      1. 10.4.1 Laying out the project structure
      2. 10.4.2 Creating an entry point for the GraphQL server
      3. 10.4.3 Implementing query resolvers
      4. 10.4.4 Implementing type resolvers
      5. 10.4.5 Handling query parameters
      6. 10.4.6 Implementing mutation resolvers
      7. 10.4.7 Building resolvers for custom scalar types
      8. 10.4.8 Implementing field resolvers
    5. Summary
  20. Part 4. Securing, testing, and deploying microservice APIs
  21. 11 API authorization and authentication
    1. 11.1 Setting up the environment for this chapter
    2. 11.2 Understanding authentication and authorization protocols
      1. 11.2.1 Understanding Open Authorization
      2. 11.2.2 Understanding OpenID Connect
    3. 11.3 Working with JSON Web Tokens
      1. 11.3.1 Understanding the JWT header
      2. 11.3.2 Understanding JWT claims
      3. 11.3.3 Producing JWTs
      4. 11.3.4 Inspecting JWTs
      5. 11.3.5 Validating JWTs
    4. 11.4 Adding authorization to the API server
      1. 11.4.1 Creating an authorization module
      2. 11.4.2 Creating an authorization middleware
      3. 11.4.3 Adding CORS middleware
    5. 11.5 Authorizing resource access
      1. 11.5.1 Updating the database to link users and orders
      2. 11.5.2 Restricting user access to their own resources
    6. Summary
  22. 12 Testing and validating APIs
    1. 12.1 Setting up the environment for API testing
    2. 12.2 Testing REST APIs with Dredd
      1. 12.2.1 What is Dredd?
      2. 12.2.2 Installing and running Dredd’s default test suite
      3. 12.2.3 Customizing Dredd’s test suite with hooks
      4. 12.2.4 Using Dredd in your API testing strategy
    3. 12.3 Introduction to property-based testing
      1. 12.3.1 What is property-based testing?
      2. 12.3.2 The traditional approach to API testing
      3. 12.3.3 Property-based testing with Hypothesis
      4. 12.3.4 Using Hypothesis to test a REST API endpoint
    4. 12.4 Testing REST APIs with Schemathesis
      1. 12.4.1 Running Schemathesis’s default test suite
      2. 12.4.2 Using links to enhance Schemathesis’ test suite
    5. 12.5 Testing GraphQL APIs
      1. 12.5.1 Testing GraphQL APIs with Schemathesis
    6. 12.6 Designing your API testing strategy
    7. Summary
  23. 13 Dockerizing microservice APIs
    1. 13.1 Setting up the environment for this chapter
    2. 13.2 Dockerizing a microservice
    3. 13.3 Running applications with Docker Compose
    4. 13.4 Publishing Docker builds to a container registry
    5. Summary
  24. 14 Deploying microservice APIs with Kubernetes
    1. 14.1 Setting up the environment for this chapter
    2. 14.2 How Kubernetes works: The “CliffsNotes” version
    3. 14.3 Creating a Kubernetes cluster with EKS
    4. 14.4 Using IAM roles for Kubernetes service accounts
    5. 14.5 Deploying a Kubernetes load balancer
    6. 14.6 Deploying microservices to the Kubernetes cluster
      1. 14.6.1 Creating a deployment object
      2. 14.6.2 Creating a service object
      3. 14.6.3 Exposing services with ingress objects
    7. 14.7 Setting up a serverless database with AWS Aurora
      1. 14.7.1 Creating an Aurora Serverless database
      2. 14.7.2 Managing secrets in Kubernetes
      3. 14.7.3 Running the database migrations and connecting our service to the database
    8. 14.8 Updating the OpenAPI specification with the ALB’s hostname
    9. 14.9 Deleting the Kubernetes cluster
    10. Summary
  25. Appendix A. Types of web APIs and protocols
    1. A.1 The dawn of APIs: RPC, XML-RPC, and JSON-RPC
    2. A.2 SOAP and the emergence of API standards
    3. A.3 RPC strikes again: Fast exchanges over gRPC
    4. A.4 HTTP-native APIs with REST
    5. A.5 Granular queries with GraphQL
  26. Appendix B. Managing an API’s life cycle
    1. B.1 Versioning strategies for evolving APIs
    2. B.2 Managing the life cycle of your APIs
  27. Appendix C. API authorization using an identity provider
    1. C.1 Using an identity as a service provider
    2. C.2 Using the PKCE authorization flow
    3. C.3 Using the client credentials flow
    4. C.4 Authorizing requests in the Swagger UI
  28. index
  29. inside back cover

Product information

  • Title: Microservice APIs
  • Author(s): Jose Haro
  • Release date: February 2023
  • Publisher(s): Manning Publications
  • ISBN: 9781617298417