Index of every page on this site: llms.txt
All skills
davidortinau avatar

/maui-rest-api

@79bb4bf
Run it yourself

Guidance for consuming REST APIs in .NET MAUI apps. Covers HttpClient setup with System.Text.Json, DI registration, service interface/implementation pattern, full CRUD operations (GET, POST, PUT, DELETE), error handling, platform-specific clear-text traffic configuration, and async/await best practices. USE FOR: "REST API", "HttpClient", "call API", "GET request", "POST request", "API service", "JSON deserialization", "CRUD operations", "clear-text traffic", "consume API MAUI". DO NOT USE FOR: Aspire service discovery (use maui-aspire), authentication token handling (use maui-authentication), or local database storage (use maui-sqlite-database).

Use this Skill: https://skilld.dev/gh/davidortinau/maui-skills/maui-rest-api

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈167 tokens for metadata: the name and description. ≈1.1k when used: this file. ≈1.3k more on demand in 1 file.

Description uses 8.4% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈669 characters, or 8.4%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

REST API Consumption — Gotchas & Best Practices

Common Mistakes

1. Creating HttpClient per request

// ❌ Creates socket exhaustion — each instance opens a new connection
public async Task<List<Item>> GetItemsAsync()
{
    using var client = new HttpClient();
    var response = await client.GetAsync("https://api.example.com/items");
    // ...
}

// ✅ Register once in DI, inject everywhere
builder.Services.AddSingleton(sp => new HttpClient
{
    BaseAddress = new Uri("https://api.example.com")
});

2. Blocking with .Result or .Wait()

// ❌ Deadlocks on the UI thread
var items = _apiService.GetItemsAsync().Result;

// ✅ Always use async/await
var items = await _apiService.GetItemsAsync();

3. Deserializing before checking status

// ❌ Tries to deserialize error HTML/JSON as your model
var content = await response.Content.ReadAsStringAsync();
var items = JsonSerializer.Deserialize<List<Item>>(content, _jsonOptions);

// ✅ Check status first
response.EnsureSuccessStatusCode();
var content = await response.Content.ReadAsStringAsync();
var items = JsonSerializer.Deserialize<List<Item>>(content, _jsonOptions) ?? [];

4. Hardcoding BaseAddress in service methods

// ❌ Absolute URIs in every method — hard to change, easy to typo
await _httpClient.GetAsync("https://api.example.com/api/items");

// ✅ Set BaseAddress in DI, use relative URIs in methods
await _httpClient.GetAsync("api/items");

5. Missing error handling for network failures

// ❌ Crashes on network timeout, DNS failure, etc.
var items = await _apiService.GetItemsAsync();

// ✅ Catch both network and deserialization errors
try
{
    var items = await _apiService.GetItemsAsync();
}
catch (HttpRequestException ex) { /* network or HTTP error */ }
catch (JsonException ex) { /* malformed response */ }

Platform Pitfalls

⚠️ Clear-text HTTP blocked on emulators/simulators

Local dev servers on http:// are blocked by default. Configure exceptions:

  • Android: needs network_security_config.xml with cleartextTrafficPermitted="true" for 10.0.2.2
  • iOS/Mac Catalyst: needs NSAllowsLocalNetworking in Info.plist

⚠️ Android emulator uses 10.0.2.2 for localhost

The Android emulator maps 10.0.2.2 to the host machine. localhost refers to the emulator itself.

// ❌ On Android emulator, this hits the emulator, not your dev machine
new Uri("http://localhost:5000")

// ✅ Use the emulator's host loopback address
new Uri("http://10.0.2.2:5000")

iOS simulators use localhost directly.

⚠️ Inconsistent JSON casing

APIs typically use camelCase; C# properties are PascalCase. Without JsonSerializerOptions, deserialization silently returns default values.

// ❌ Properties stay null/default — no error thrown
JsonSerializer.Deserialize<Item>(content);

// ✅ Configure casing policy
private static readonly JsonSerializerOptions _jsonOptions = new()
{
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
    PropertyNameCaseInsensitive = true
};

Decision Framework

Scenario Error handling approach
Failure is unexpected (auth'd endpoints) EnsureSuccessStatusCode() — throws HttpRequestException
Need to branch on status codes Check IsSuccessStatusCode or response.StatusCode
Network may be unreliable (mobile) Wrap in try/catch for HttpRequestException
Response format may vary Also catch JsonException

Checklist

  • HttpClient registered as singleton or via IHttpClientFactory — never created per-request
  • BaseAddress set in DI; service methods use relative URIs
  • JsonSerializerOptions with CamelCase policy applied consistently
  • IsSuccessStatusCode or EnsureSuccessStatusCode() checked before deserializing
  • try/catch for HttpRequestException and JsonException in ViewModel calls
  • All API calls use async/await — no .Result or .Wait()
  • Service interface pattern used so ViewModels depend on abstractions
  • Android clear-text config for local dev (10.0.2.2)
  • iOS NSAllowsLocalNetworking for local dev

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 warning2mo4 checks · Risk SAFE
  • Gen Agent Trust Hub2mo

    This skill provides standard architectural guidance and code samples for consuming REST APIs in .NET MAUI applications. No security risks were identified.

  • Socket2mo

    No alerts

  • Snyk2mo

    Risk: LOW · No issues

  • Runlayer9mo

    1/1 file flagged

Signed by skilld at 79bb4bf. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last month.

Steadyupdated 8 months ago

README badge

README badge for davidortinau/maui-skills/maui-rest-api