Your First Request

This guide walks you through making your first HTTP request with CurlDotNet.

Prerequisites

Before you begin, ensure you have:

See the Installation Guide if you need help setting up.

The Simplest Request

The easiest way to make a request is to just paste a curl command:

using CurlDotNet;

// Make a GET request - it's that simple!
var result = await Curl.ExecuteAsync("curl https://httpbin.org/get");

Console.WriteLine(result.Body);

That’s it! You’ve made your first HTTP request with CurlDotNet.

Understanding the Response

Every request returns a CurlResult object with useful properties:

var result = await Curl.ExecuteAsync("curl https://httpbin.org/get");

// Check if the request succeeded (status 200-299)
Console.WriteLine($"Success: {result.IsSuccess}");

// Get the HTTP status code
Console.WriteLine($"Status Code: {result.StatusCode}");

// Get the response body as a string
Console.WriteLine($"Body: {result.Body}");

// Access response headers
foreach (var header in result.Headers)
{
    Console.WriteLine($"{header.Key}: {header.Value}");
}

Three Ways to Make Requests

CurlDotNet offers three approaches - use whichever fits your style:

1. String API (Copy & Paste)

Perfect for when you have a curl command from documentation:

// Just paste any curl command from API docs, Stack Overflow, etc.
var result = await Curl.ExecuteAsync(@"
    curl https://api.github.com/users/octocat \
      -H 'User-Agent: MyApp'
");

The User-Agent header is optional: like curl, CurlDotNet sends User-Agent: curl/8.7.1 when you do not set one.

2. Builder API (Type-Safe)

Get IntelliSense and compile-time checking:

var result = await CurlRequestBuilder
    .Get("https://api.github.com/users/octocat")
    .WithHeader("User-Agent", "MyApp")
    .ExecuteAsync();

3. Quick Methods

Convenience methods for simple operations:

// Simple GET
var result = await Curl.GetAsync("https://httpbin.org/get");

// POST with data
var result = await Curl.PostAsync("https://httpbin.org/post", "name=John");

// POST with JSON
var result = await Curl.PostJsonAsync("https://httpbin.org/post", new { name = "John" });

// Download a file
await Curl.DownloadAsync("https://example.com/file.pdf", "output.pdf");

Working with JSON

Most APIs return JSON. CurlDotNet makes it easy to work with. ParseJson<T>() matches property names case-insensitively, so the camelCase keys login, name and followers bind to the PascalCase properties below:

// Define your model
public class GitHubUser
{
    public string Login { get; set; }
    public string Name { get; set; }
    public int Followers { get; set; }
}

// Make the request and parse JSON
var result = await Curl.ExecuteAsync("curl https://api.github.com/users/octocat");

if (result.IsSuccess)
{
    var user = result.ParseJson<GitHubUser>();
    Console.WriteLine($"User: {user.Name} has {user.Followers} followers");
}

Error Handling

Always handle potential errors:

try
{
    var result = await Curl.ExecuteAsync("curl https://api.example.com/data");

    if (result.IsSuccess)
    {
        Console.WriteLine("Success!");
        Console.WriteLine(result.Body);
    }
    else
    {
        Console.WriteLine($"HTTP Error: {result.StatusCode}");
    }
}
catch (CurlDotNet.Exceptions.CurlTimeoutException ex)
{
    Console.WriteLine($"Request timed out after {ex.Timeout}");   // only when you set -m / --max-time
}
catch (CurlDotNet.Exceptions.CurlCouldntResolveHostException ex)
{
    Console.WriteLine($"Could not resolve host: {ex.Hostname}");
}
catch (CurlDotNet.Exceptions.CurlException ex)
{
    Console.WriteLine($"Curl error: {ex.Message}");
}

Common curl Options

Here are some frequently used curl options:

Option Description Example
-X METHOD Set HTTP method -X POST
-H 'Header: Value' Add header -H 'Authorization: Bearer token'
-d 'data' Send data in body -d '{"name":"John"}'
-u user:pass Basic authentication -u admin:secret
-o file Save output to file -o response.json
-L Follow redirects -L
-k Skip SSL verification -k (dev only!)
--max-time 30 Timeout in seconds --max-time 30

Complete Example

Here’s a complete example that puts it all together:

using System;
using System.Threading.Tasks;
using CurlDotNet;

class Program
{
    static async Task Main()
    {
        Console.WriteLine("Fetching GitHub user information...\n");

        try
        {
            // Make the request
            var result = await Curl.ExecuteAsync(@"
                curl https://api.github.com/users/octocat \
                  -H 'User-Agent: CurlDotNet-Example' \
                  -H 'Accept: application/json'
            ");

            // Check result
            if (result.IsSuccess)
            {
                using var doc = System.Text.Json.JsonDocument.Parse(result.Body);
                var user = doc.RootElement;
                Console.WriteLine($"Username: {user.GetProperty("login")}");
                Console.WriteLine($"Name: {user.GetProperty("name")}");
                Console.WriteLine($"Public Repos: {user.GetProperty("public_repos")}");
                Console.WriteLine($"Followers: {user.GetProperty("followers")}");
            }
            else
            {
                Console.WriteLine($"Error: {result.StatusCode}");
            }
        }
        catch (Exception ex)
        {
            Console.WriteLine($"Failed: {ex.Message}");
        }
    }
}

Next Steps

Now that you’ve made your first request:

  1. Configure CurlDotNet - Set timeouts, proxies, and more
  2. Browse the Cookbook - Ready-to-use recipes
  3. Learn More Tutorials - Deep dive into features
  4. API Reference - Complete API documentation

Need Help?