NaturalApi 1.0.6

NaturalApi

Fluent API testing that actually reads like English

NaturalApi turns your API tests into sentences you can read aloud. No boilerplate. No ceremony. Just clarity.

Why another API library?

Because this...

var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Get, "https://api.example.com/users/1");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
var response = await client.SendAsync(request);
var content = await response.Content.ReadAsStringAsync();
var user = JsonSerializer.Deserialize<User>(content);
Assert.AreEqual(200, (int)response.StatusCode);
Assert.IsNotNull(user);

…is the kind of code people write once, copy forever, and never want to look at again.

Now read this:

var user = await Api.For("/users/1")
    .UsingAuth("Bearer token")
    .Get()
    .ShouldReturn<User>();

That's not just cleaner...it's readable. It says exactly what it does. And when you come back to it six months later, you'll still know what it means.

Quick Start

dotnet add package NaturalApi

using NaturalApi;

// Simple GET request
var users = await Api.For("https://api.example.com/users")
    .Get()
    .ShouldReturn<List<User>>();

// POST with authentication
var newUser = await Api.For("/users")
    .UsingAuth("Bearer your-token")
    .Post(new { name = "John", email = "john@example.com" })
    .ShouldReturn<User>(status: 201);

Get started →

Documentation

Getting Started

• Getting Started - Installation, first API call, basic setup
• Configuration - Base URLs, timeouts, default headers, DI setup
• Examples - Real-world scenarios and complete examples

Core Features

• Request Building - Headers, query params, path params, cookies
• HTTP Verbs - GET, POST, PUT, PATCH, DELETE with examples
• Assertions - ShouldReturn variations, validation patterns
• Authentication - Auth providers, caching, per-user tokens

Advanced Topics

• Error Handling - Exception types, debugging, troubleshooting
• Testing Guide - Unit testing with mocks, integration testing
• Extensibility - Custom executors, validators, auth providers
• Reporting - Configurable reporters, DI factory and examples

Reference

• API Reference - Complete interface and class documentation
• Troubleshooting - Common issues and solutions
• Contributing - Architecture internals and contribution guidelines

Design & Philosophy

• Philosophy & Design Principles - Core design philosophy
• Fluent Syntax Reference - Complete grammar and method reference
• Dependency Injection Guide - DI patterns and ServiceCollectionExtensions
• Architecture Overview - Internal design and implementation

The Core Grammar

Every test reads like this:

Api.For(endpoint)
   .WithHeaders(...)      // Optional
   .WithQueryParams(...)  // Optional
   .UsingAuth(...)        // Optional
   .<HttpVerb>(body)      // GET, POST, PUT, etc.
   .ShouldReturn<T>(...)  // Validate response

Or in practice:

await Api.For("/orders/123")
    .UsingAuth("Bearer token")
    .Get()
    .ShouldReturn<Order>(status: 200, body: o => o.Total > 0);

You can actually read that aloud. And it still compiles.

📚 Learn More: See the complete Fluent Syntax Reference for all available methods and patterns.

Five things you can express in one line

// 1. Simple GET
await Api.For("/users").Get().ShouldReturn<List<User>>();

// 2. POST with validation
await Api.For("/users").Post(newUser).ShouldReturn<User>(status: 201);

// 3. Authenticated request
await Api.For("/protected").UsingAuth("Bearer token").Get();

// 4. Query parameters
await Api.For("/search").WithQueryParam("q", "api testing").Get();

// 5. Delete with assertion
await Api.For("/users/1").Delete().ShouldReturn(204);

Readable, predictable, and type-safe. Because testing APIs shouldn't feel like writing networking code.

🔗 Related: Learn about HTTP Verbs, Assertions, and Authentication for more advanced patterns.

License

MIT. Do what you want, just don't ruin the readability.

Contributing

Good ideas welcome. Over-engineering isn't. See our Contributing Guide for details.

Related Topics

• Getting Started - Your first API call and basic setup
• Configuration - Base URLs, timeouts, and DI setup
• Examples - Real-world scenarios and complete examples
• Troubleshooting - Common issues and solutions
• API Reference - Complete interface documentation