Building a type-safe REST client with Refit and Newtonsoft.Json

REST APIs sit at the centre of most modern software stacks, and Australian developers from Sydney to Brisbane to Perth spend a significant share of their week calling endpoints belonging to someone else's platform. Whether you are wiring up a checkout flow for a Melbourne fintech, pulling shipment data from a logistics provider in Adelaide, or integrating with the Commonwealth Bank's public APIs, you end up writing the same plumbing: build a URL, attach headers, serialise a payload, await a response, then deserialise the body. Over time, that plumbing becomes a maintenance cost.

Many teams reach for HttpClient directly and write helper methods that wrap each call. Others adopt libraries such as RestSharp, Flurl, or Refit to remove the ceremony. Refit takes a distinctive approach by treating the HTTP contract as a C# interface. You declare an interface, annotate methods with HTTP verbs and routes, and the library generates the network code at runtime. The result reads like a service definition rather than a tangle of string concatenation.

Newtonsoft.Json pairs naturally with Refit for projects that need fine-grained control over JSON serialisation. While System.Text.Json has matured into a fast and capable library, Newtonsoft.Json still powers many existing codebases across Australian enterprises, particularly in the financial services sector around Sydney's Barangaroo precinct. Combining the two libraries gives teams a familiar serialisation experience backed by a clean declarative API surface.

This article walks through the practical steps of creating a REST client with Refit and Newtonsoft.Json, from project setup through to testing and resilience. You will see code samples, a side-by-side comparison with alternative approaches, and a short set of recommendations gathered from teams that have rolled Refit out across production systems.

Why a declarative HTTP client approach appeals to .NET teams

The conventional pattern of instantiating HttpClient, building HttpRequestMessage, and handling the response stream by hand works, but it leaves a lot of decision-making to the developer on every call. Each method ends up restating things like base addresses, JSON media types, and error policies. When a team in Melbourne's REA Group or a similar property platform needs to integrate with a dozen internal services, that repetition turns into review friction.

Refit collapses the verb, route, and return type into an interface method. A GET becomes a method with [Get("/users/{id}")] returning a Task<User>. A POST becomes a method with [Post("/users")] accepting a User body. The library's RequestBuilder reflection code then assembles the actual HttpClient call. From the caller's perspective, the dependency looks like any other injected service, which makes it straightforward to mock in tests.

This pattern also tends to play well with code review. Reviewers see the route, the payload shape, and the return type on a single declaration. Less context switching means faster approvals, particularly helpful for distributed teams spread between Sydney, Adelaide, and regional Queensland hubs that often share pull requests across time zones. AEST sits ten hours ahead of UTC, so any reduction in back-and-forth in pull requests saves a day of latency for offshore collaborators.

Another benefit shows up during onboarding. A new engineer can read the interface and understand the available operations without hunting through helper classes. For Australian consultancies that frequently rotate staff between client projects, that readability translates directly into billable hours saved on familiarisation.

Setting up Refit with Newtonsoft.Json in a project

Adding Refit to a .NET project starts in the usual way: open the Package Manager Console or your terminal of choice and add the NuGet packages. The core package is Refit, and the JSON adapter that bridges Refit to Newtonsoft.Json lives in Refit.Newtonsoft.Json. If you plan to use Polly for retries and circuit breaking, Refit.Polly is also worth including from the start.

A minimal registration in a console application looks like this. You build a RefitSettings instance, hand it a NewtonsoftJsonContentSerializer, and then call RestService.For<IMyApi> to obtain a typed client. The JsonSerializerSettings you configure behave exactly as they would in any other Newtonsoft.Json call site. Custom converters, contract resolvers, date format strings, and NullValueHandling all flow through unchanged.

In an ASP.NET Core application hosted in Azure Australia Central or on premises behind an Australian government network, the registration typically goes into Program.cs or Startup.cs. Using AddRefitClient<T> along with the UsingNewtonsoftJson extension method configures the typed client with the framework's dependency injection container. HttpClient message handlers, including Polly's retry and circuit breaker policies, attach at this point so they cover every request issued through the client.

Defining the API contract with interfaces and attributes

The interface itself is where Refit really shines. You write methods that look like ordinary C# code, decorate them with attributes describing the HTTP operation, and let the library do the rest. A method returning Task<T> is treated as expecting a JSON body. A method returning Task<HttpResponseMessage> exposes the raw response, which is useful when you need headers or status codes. A method returning Task<IObservable<T>> is treated as a streaming endpoint.

Consider a simple payments interface for an Australian buy-now-pay-later style service. Routes, body parameters, and return types are declared on the interface, and Refit handles serialisation, request building, and deserialisation behind the scenes.

Route parameters in curly braces map directly to method arguments by name. Query string parameters are picked up automatically from simple arguments. [Body] marks the serialised payload. [Header("Authorization")] attaches headers per method, which is handy for endpoints that demand per-call signatures, a pattern common in Australian banking APIs that follow the Consumer Data Standards.

When the response model uses property names that differ from the wire format, a [JsonProperty] attribute from Newtonsoft.Json handles the mapping without any extra configuration. The same applies to polymorphic deserialisation, enum string conversion, and custom date parsers. Because Refit delegates serialisation entirely to the configured JSON library, every Newtonsoft.Json convention you already use keeps working.

Authentication, headers, and error responses

Most Australian enterprise APIs gate access behind OAuth 2.0 client credentials, mutual TLS, or signed request schemes. Refit supports these patterns through three layers: the Authorization header attribute, a custom HttpClientHandler or DelegatingHandler attached during registration, and an IAuthenticationToken service for tokens that refresh over time.

For a static API key, [Headers("Authorization: Bearer")] string authToken on a method parameter sends a header per call. For dynamic tokens, a DelegatingHandler subclass reads from an injected token cache, attaches the header, and forwards the request. If you target an Australian government endpoint hosted behind the Digital Transformation Agency's platform, you will likely need to combine this with mTLS, which is configured on the underlying HttpMessageHandler rather than in Refit itself.

Error handling often needs care. Returning Task<T> makes the library throw ApiException for any non-success status. Returning Task<ApiResponse<T>> exposes the response, status, and error body without throwing, which works well when you want to surface validation errors from the API to your own UI. A common pattern in Australian fintech applications is to combine both: success returns the typed model, and validation failures return a structured error envelope that the caller can display directly.

Logging also belongs in this layer. Attaching an ILogger to the Refit settings via HttpMessageInvoker or wrapping the typed client in a logging handler gives visibility into outbound calls. That visibility matters when you operate across multiple regions from Sydney to Perth, because slow calls to overseas data centres can drag down user experience in ways that only show up in production telemetry.

Testing, mocking, and resilience patterns

Unit testing a Refit client is straightforward because the dependency is just an interface. You can substitute NSubstitute, Moq, or FakeItEasy and return canned responses. There is no need to spin up an HttpClient or fake a web server for the typical happy path. For integration tests that exercise the real serialisation pipeline, the MockHttp library plus a test instance of your interface lets you assert request shapes and respond with controlled JSON.

Resilience comes from Polly. The Refit.Polly package wires IAsyncPolicy<HttpResponseMessage> into the typed client so that retries, timeouts, and circuit breakers cover every call. A reasonable starting point for an Australian consumer-facing API is three retries with exponential backoff and a circuit breaker that opens after a burst of failures. Always combine those with an overall request timeout shorter than your caller's timeout, otherwise retries will cascade upward and exhaust upstream budgets.

Recommendations gathered from production rollouts across Australian engineering teams:

• Pin your Newtonsoft.Json version explicitly to avoid silent breaking changes from transitive dependencies.
• Configure JsonSerializerSettings once in a shared factory rather than re-creating them per client, so settings stay consistent across services.
• Use ApiResponse<T> for endpoints that need to surface validation errors rather than treating every non-200 as an exception.
• Add a Polly timeout policy that is shorter than any caller timeout to prevent cascading failures.
• Log the outbound URL and correlation ID for every request so support engineers can trace calls across services.