api-tools 0.6.1

An API tools library for Rust
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111

# API Tools

[![Build status](https://github.com/fabienbellanger/api-tools/actions/workflows/CI.yml/badge.svg?branch=main)](https://github.com/fabienbellanger/api-tools/actions/workflows/CI.yml)
[![Crates.io](https://img.shields.io/crates/v/api-tools)](https://crates.io/crates/api-tools)
[![Documentation](https://docs.rs/api-tools/badge.svg)](https://docs.rs/api-tools)

> Toolkit for API in Rust

API Tools is a Rust library providing utilities for developing robust, consistent, and secure APIs.
It offers ready-to-use layers, extractors, error handling, and helpers designed to simplify API development, especially
with the Axum framework. The toolkit aims to standardize common API patterns and reduce boilerplate in your Rust
projects.

## Installation

For standard functionalities, no additional dependencies are required:

```toml
[dependencies]
api-tools = "*"
```

If you need all [features](#Features-list), you can use the `full` feature:

```toml
[dependencies]
api-tools = { version = "*", features = ["full"] }
```

Or you can use `cargo add` command:

```bash
cargo add api-tools
cargo add api-tools -F full
```

## Features list

| Name         | Description                       | Default |
| ------------ | --------------------------------- | :-----: |
| `axum`       | Enable Axum feature               |   ❌    |
| `prometheus` | Enable Prometheus metrics feature |   ❌    |
| `full`       | Enable all features               |   ❌    |

## Components

### Value objects

| Name          | Description                                                                                |
| ------------- | ------------------------------------------------------------------------------------------ |
| `UtcDateTime` | A wrapper around `chrono::DateTime` to handle date and time values in UTC                  |
| `Timezone`    | A wrapper around `chrono_tz::Tz` to handle time zones                                      |
| `Pagination`  | A struct to handle pagination parameters, including page number, page size and total count |
| `QuerySort`   | A struct to handle sorting query parameters, including field and direction                 |

### Axum

#### Security

| Name  | Description                              |
| ----- | ---------------------------------------- |
| `Jwt` | A wrapper for JWT generation and parsing |

#### Layers

| Name               | Description                                                                                                                              |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `BasicAuthLayer`   | Provides HTTP Basic Authentication middleware for protecting routes with username and password                                           |
| `CorsLayer`        | Adds Cross-Origin Resource Sharing (CORS) headers to responses, allowing or restricting resource sharing between different origins       |
| `HttpErrorsLayer`  | Middleware for intercepting and customizing HTTP error responses, enabling standardized error handling across your API                   |
| `LoggerLayer`      | Logs incoming requests and outgoing responses, useful for debugging and monitoring API activity                                          |
| `RequestId`        | Middleware that generates and attaches a unique request identifier (UUID) to each incoming request for traceability                      |
| `TimeLimiterLayer` | Middleware that restricts API usage to specific time slots. Outside of these allowed periods, it returns a 503 Service Unavailable error |
| `PrometheusLayer`  | Middleware that collects and exposes Prometheus-compatible metrics for monitoring API performance and usage                              |

##### Utility functions

| Name                  | Description                                                              |
| --------------------- | ------------------------------------------------------------------------ |
| `body_from_parts`     | Construct a response body from `Parts`, status code, message and headers |
| `header_value_to_str` | Convert `HeaderValue` to `&str`                                          |

#### Extractors

| Name               | Description                                                            |
| ------------------ | ---------------------------------------------------------------------- |
| `ExtractRequestId` | Extracts the unique request identifier (UUID) from the request headers |
| `Path`             | Extracts and deserializes path parameters from the request URL         |
| `Query`            | Extracts and deserializes query string parameters from the request URL |

#### Response helpers

| Name               | Description                                                                                                 |
| ------------------ | ----------------------------------------------------------------------------------------------------------- |
| `ApiSuccess`       | Represents a successful API response (Status code and data in JSON). It implements the `IntoResponse` trait |
| `ApiError`         | Represents a list of HTTP errors                                                                            |
| `ApiErrorResponse` | Encapsulates the details of an API error response, including the status code and the error message          |

#### Handlers

| Name                | Description                                                                                       |
| ------------------- | ------------------------------------------------------------------------------------------------- |
| `PrometheusHandler` | Handler that exposes Prometheus metrics endpoint, allowing metrics scraping by Prometheus servers |

## Code coverage

- [2025-06-26] `41.39% coverage, 233/563 lines covered`

## To-Do list

- [ ] Add more documentation