How to add retry logic with gentleman?

Use the gentleman-retry plugin, which provides configurable retry policies. Install it separately, then attach it to your client or request via the Use() method, similar to other plugins shown in examples.

Gentleman vs resty: which is better for Go HTTP clients?

Gentleman focuses on extensibility and middleware composition, ideal for custom API clients. Resty offers more built-in features out-of-the-box but is less plugin-driven. Choose Gentleman if you need fine-grained control and reuse.

How to mock HTTP requests for testing with gentleman?

Integrate the gentleman-mock plugin, which uses gock under the hood. It allows you to define mock responses and verify requests, making end-to-end testing easier, as referenced in the README.

Is gentleman good for building REST API clients?

Yes, it's well-suited for domain-specific REST API clients due to its plugin architecture and helpers for JSON/XML serialization. The inheritance model helps reuse common logic across endpoints.

How to handle authentication with gentleman plugins?

Use the built-in auth plugin to set authorization headers, or create custom plugins for complex auth flows. Plugins can intercept requests to add tokens dynamically, leveraging the middleware phases.

What are the middleware phases in gentleman?

Gentleman supports phases like request, response, error, and intercept, allowing logic execution at different HTTP lifecycle stages. This enables tasks like logging, error handling, and request modification before sending.

gentleman — Go HTTP Client Toolkit

What is gentleman?

Gentleman is a full-featured, plugin-driven HTTP client toolkit for Go that embraces extensibility and composition principles. It provides a flexible way to create rich, versatile HTTP clients using a middleware-oriented architecture, making it ideal for building domain-specific API clients. Built on top of Go's standard net/http package, it offers convenient helpers for URL templating, JSON/XML serialization, and HTTP mocking.

Target Audience

Go developers building domain-specific HTTP API clients or those needing a highly extensible and composable HTTP client layer with middleware support. It's particularly suited for engineers who require reusable client logic, such as in microservices or SDK development.

Value Proposition

Developers choose Gentleman over alternatives for its plugin-driven architecture and hierarchical middleware layer, which allow easy extension and composition of functionality like retry policies, authentication, and server discovery. Its focus on reusability through client and request entity inheritance, along with built-in multiplexing for conditional plugin execution, provides a clean, idiomatic way to manage complex HTTP client logic.

Plugin-driven, extensible HTTP client toolkit for Go

Use Cases

Best For

Building domain-specific HTTP API clients with reusable logic and middleware.
Implementing extensible HTTP clients with custom plugins for features like retry policies, authentication, or dynamic server discovery.
Creating composable HTTP client layers where conditional plugin execution based on matchers (e.g., method, host) is required.
Developing Go applications that need easy HTTP mocking for testing, integrated via plugins like gentleman-mock.
Managing complex HTTP request/response life cycles with middleware phases for interception, error handling, and traffic modification.
Structuring HTTP clients with inheritance hierarchies for shared configuration across multiple requests.

Not Ideal For

Projects requiring only simple, one-off HTTP requests without middleware or plugin overhead
High-performance applications where the layered architecture might introduce unnecessary latency
Teams seeking a large, active ecosystem of pre-built plugins beyond the core offerings
Quick prototyping or scripts where the standard net/http package is sufficient

Pros & Cons

Pros

Plugin-Driven Flexibility

Enables easy extension with built-in and third-party plugins for features like auth, retry, and mocking, as detailed in the plugins table, promoting modular design.

Hierarchical Middleware Control

Supports multiple HTTP lifecycle phases (e.g., request, response, error), allowing fine-grained interception and modification, ideal for complex client logic.

Clean Composition and Inheritance

Uses client and request entities with inheritance, plus a built-in multiplexer, for reusable and conditional plugin execution, enhancing code reusability.

Integrated Testing Support

Facilitates HTTP mocking via plugins like gentleman-mock, leveraging gock for expressive testing, as highlighted in the README examples.

Cons

Limited Third-Party Ecosystem

The plugin ecosystem is small, with few community plugins listed, relying heavily on user contributions for extended functionality.

Complex Setup and Learning Curve

Requires understanding middleware phases and plugin architecture, which can be daunting for developers accustomed to simpler HTTP clients.

Potential Performance Overhead

The layered, plugin-driven design may add overhead for basic HTTP tasks, making it less efficient than lightweight alternatives.

What is gentleman?

Target Audience

Value Proposition

Use Cases

Best For

Building domain-specific HTTP API clients with reusable logic and middleware.
Implementing extensible HTTP clients with custom plugins for features like retry policies, authentication, or dynamic server discovery.
Creating composable HTTP client layers where conditional plugin execution based on matchers (e.g., method, host) is required.
Developing Go applications that need easy HTTP mocking for testing, integrated via plugins like gentleman-mock.
Managing complex HTTP request/response life cycles with middleware phases for interception, error handling, and traffic modification.
Structuring HTTP clients with inheritance hierarchies for shared configuration across multiple requests.

Not Ideal For

Projects requiring only simple, one-off HTTP requests without middleware or plugin overhead
High-performance applications where the layered architecture might introduce unnecessary latency
Teams seeking a large, active ecosystem of pre-built plugins beyond the core offerings
Quick prototyping or scripts where the standard net/http package is sufficient

Pros & Cons

Pros

Plugin-Driven Flexibility

Enables easy extension with built-in and third-party plugins for features like auth, retry, and mocking, as detailed in the plugins table, promoting modular design.

Hierarchical Middleware Control

Supports multiple HTTP lifecycle phases (e.g., request, response, error), allowing fine-grained interception and modification, ideal for complex client logic.

Clean Composition and Inheritance

Uses client and request entities with inheritance, plus a built-in multiplexer, for reusable and conditional plugin execution, enhancing code reusability.

Integrated Testing Support

Facilitates HTTP mocking via plugins like gentleman-mock, leveraging gock for expressive testing, as highlighted in the README examples.

Cons

Limited Third-Party Ecosystem

The plugin ecosystem is small, with few community plugins listed, relying heavily on user contributions for extended functionality.

Complex Setup and Learning Curve

Requires understanding middleware phases and plugin architecture, which can be daunting for developers accustomed to simpler HTTP clients.

Potential Performance Overhead

The layered, plugin-driven design may add overhead for basic HTTP tasks, making it less efficient than lightweight alternatives.

gentleman

What is gentleman?

Overview

Use Cases

Best For

Not Ideal For

Pros & Cons

Pros

Cons

Frequently Asked Questions

Related Projects

Found a gem we're missing?

gentleman

What is gentleman?

Overview

Use Cases

Best For

Not Ideal For

Pros & Cons

Pros

Cons

Frequently Asked Questions

Related Projects

Found a gem we're missing?