Skip to content

Commit

Permalink
docs: update README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@BolajiAyodeji
BolajiAyodeji authored May 29, 2024
1 parent 3471219 commit f986d96
Showing 1 changed file with 12 additions and 219 deletions.
231 changes: 12 additions & 219 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
![APItoolkit's Logo](https://github.com/apitoolkit/.github/blob/main/images/logo-white.svg?raw=true#gh-dark-mode-only)
![APItoolkit's Logo](https://github.com/apitoolkit/.github/blob/main/images/logo-black.svg?raw=true#gh-light-mode-only)

## .NET SDK
## .NET Core SDK

[![NuGet](https://img.shields.io/badge/APItoolkit-sdk-0068ff)](https://github.com/topics/apitoolkit-sdk) [![Build Status](https://github.com/apitoolkit/apitoolkit-dotnet/workflows/.NET/badge.svg)](https://github.com/apitoolkit/apitoolkit-dotnet1/actions?query=workflow%3ACI) [![NuGet](https://img.shields.io/nuget/v/ApiToolkit.Net.svg)](https://nuget.org/packages/ApiToolkit.Net) [![Nuget](https://img.shields.io/nuget/dt/ApiToolkit.Net.svg)](https://nuget.org/packages/ApiToolkit.Net)

Expand All @@ -18,32 +18,30 @@ APItoolkit is an end-to-end API and web services management toolkit for engineer
- [Installation](#installation)
- [Configuration](#configuration)
- [Redacting Sensitive Data](#redacting-sensitive-data)
- [JSONPath Example](#jsonpath-example)
- [Configuration Example](#configuration-example)
- [Monitoring outgiong requests](#monitoring-outgoing-requests)
- [Error Reporting](#error-reporting)
- [Contributing and Help](#contributing-and-help)
- [License](#license)

---

## Installation

Kindly run the following command to install the package:
Kindly run the command below to install the package:

```sh
dotnet add package ApiToolkit.Net
```

## Configuration

Now you can initialize APItoolkit in your application's entry point (e.g `Program.cs`) like so:
Next, initialize APItoolkit in your application's entry point (e.g `Program.cs`) like so:

```csharp
using ApiToolkit.Net;

var config = new Config
{
Debug = true, # Set debug flags to false in production
ApiKey = "{Your_APIKey}"
ApiKey = "{ENTER_YOUR_API_KEY_HERE}"
};
var client = await APIToolkit.NewClientAsync(config);

Expand All @@ -54,226 +52,21 @@ app.Use(async (context, next) =>
await apiToolkit.InvokeAsync(context);
});

# app.UseEndpoint(..)
# app.UseEndpoint(..)
# other middleware and logic
# ...
```

> [!NOTE]
>
> Please make sure the APItoolkit middleware is added before `UseEndpoint` and other middleware are initialized.
> [!IMPORTANT]
>
> The `{Your_APIKey}` field should be replaced with the API key generated from the APItoolkit dashboard.

## Redacting Sensitive Data

If you have fields that are sensitive and should not be sent to APItoolkit servers, you can mark those fields to be redacted in two ways:
- This client SDK (the fields will never leave your servers in the first place).
- The APItoolkit dashboard (the fields will be transported from your servers first and then redacted on the edge before further processing).

To mark a field for redacting via this SDK, you need to provide additional arguments to the `config` variable with paths to the fields that should be redacted. There are three (3) potential arguments that you can provide to configure what gets redacted.
1. `RedactHeaders`: A list of HTTP header keys (e.g., `COOKIE` (redacted by default), `CONTENT-TYPE`, etc.).
2. `RedactRequestBody`: A list of JSONPaths from the request body (if the request body is a valid JSON).
3. `RedactResponseBody`: A list of JSONPaths from the response body (if the response body is a valid JSON).

### JSONPath Example

Given the following JSON object:

```JSON
{
"store": {
"books": [
{
"category": "reference",
"author": "Nigel Rees",
"title": "Sayings of the Century",
"price": 8.95
},
{
"category": "fiction",
"author": "Evelyn Waugh",
"title": "Sword of Honour",
"price": 12.99
},
...
],
"bicycle": {
"color": "red",
"price": 19.95
}
},
...
}
```
> - Please make sure the APItoolkit middleware is added before `UseEndpoint` and other middleware are initialized.
> - The `{ENTER_YOUR_API_KEY_HERE}` demo string should be replaced with the [API key](https://apitoolkit.io/docs/dashboard/settings-pages/api-keys) generated from the APItoolkit dashboard.
Examples of valid JSONPaths would be:

- `$.store.books` (In this case, APItoolkit will replace the `books` field inside the store object with the string `[CLIENT_REDACTED]`).
- `$.store.books[*].author` (In this case, APItoolkit will replace the `author` field in all the objects in the `books` list inside the `store` object with the string `[CLIENT_REDACTED]`).

For more examples and a detailed introduction to JSONPath, please take a look at [this guide](https://support.smartbear.com/alertsite/docs/monitors/api/endpoint/jsonpath.html) or [this cheatsheet](https://lzone.de/#/LZone%20Cheat%20Sheets/Languages/JSONPath).

### Configuration Example

Here's an example of what the configuration in your entry point (`Program.cs`) would look like with the redacted fields configured:

```csharp
var config = new Config
{
Debug = true, # Set debug flags to false in production
ApiKey = "{Your_APIKey}",
RedactHeaders = new List<string> { "HOST", "CONTENT-TYPE" },
RedactRequestBody = new List<string> { "$.password", "$.payment.credit_cards[*].cvv", "$.user.addresses[*]" },
RedactResponseBody = new List<string> { "$.title", "$.store.books[*].author" }
};
var client = await APIToolkit.NewClientAsync(config);

# Register the middleware to use the initialized client
app.Use(async (context, next) =>
{
var apiToolkit = new APIToolkit(next, client);
await apiToolkit.InvokeAsync(context);
})
```
<br />

> [!NOTE]
> [!IMPORTANT]
>
> While the `RedactHeaders` config field accepts a list of case-insensitive headers, `RedactRequestBody` and `RedactResponseBody` expect a list of JSONPath strings as arguments. Also, the list of items to be redacted will be applied to all endpoint requests and responses on your server.

## Monitoring Outgoing Requests

Apitoolkit allows your to monitor request you make from your application just like request that come into your app. Outgoing request are associated with the request that triggers them when the request context is passed otherwise they appear as a standalone log in the APIToolkit log explorer.
To monitor outgoing request

Example

```csharp
using ApiToolkit.Net;

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

var config = new Config
{
ApiKey = "<YOUR_API_KEY>"
};
var client = await APIToolkit.NewClientAsync(config);

app.Use(async (context, next) =>
{
var apiToolkit = new APIToolkit(next, client);
await apiToolkit.InvokeAsync(context);
});

app.MapGet("/monitor-requets", async (context) =>
{
using var httpClient = new HttpClient(client.APIToolkitObservingHandler(context));
var response = await httpClient.GetAsync("https://jsonplaceholder.typicode.com/posts/1");
var body = await response.Content.ReadAsStringAsync();
await context.Response.WriteAsync(body);
});
```


The observing handler also take and optional configuration options which include the following fields

`PathWildCard`: For urls with path params setting PathWildCard will be used as the url_path
`RedactHeaders`: A string list of headers to redact
`RedactResponseBody`: A string list of json paths to redact from response body
`RedactRequestBody`: A string list of json paths to redact from request body

### Full configuration example
```csharp
using ApiToolkit.Net;

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

var config = new Config
{
ApiKey = "<YOUR_API_KEY>"
};
var client = await APIToolkit.NewClientAsync(config);

app.Use(async (context, next) =>
{
var apiToolkit = new APIToolkit(next, client);
await apiToolkit.InvokeAsync(context);
});


app.MapGet("/monitor-requets", async (context) =>
{
var observingHandlerOptions = new ATOptions
{
PathWildCard = "/posts/{id}", // url_path will be /posts/{id} instead of /posts/1
RedactHeaders = ["User-Agent"],
RedactRequestBody = ["$.user.password"],
RedactResponseBody = ["$.user.data.email"]
};

using var httpClient = new HttpClient(client.APIToolkitObservingHandler(context, observingHandlerOptions));
var response = await httpClient.GetAsync("https://jsonplaceholder.typicode.com/posts/1");
var body = await response.Content.ReadAsStringAsync();
await context.Response.WriteAsync(body);
});
```

## Error Reporting

APIToolkit detects a lot of API issues automatically, but it's also valuable to report and track errors.

This helps you associate more details about the backend with a given failing request. If you've used sentry, or rollback, or bugsnag, then you're likely aware of this functionality.

To report errors, simply call `ReportError` method of the APIToolkit client

Example

```csharp

using ApiToolkit.Net;

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

var config = new Config
{
ApiKey = "<YOUR_API_KEY>"
};

var client = await APIToolkit.NewClientAsync(config);

app.Use(async (context, next) =>
{
var apiToolkit = new APIToolkit(next, client);
await apiToolkit.InvokeAsync(context);
});

app.MapGet("/error-tracking", async context =>
{
try
{
// Attempt to open a non-existing file
using (var fileStream = System.IO.File.OpenRead("nonexistingfile.txt"))
{
// File opened successfully, do something if needed
}
await context.Response.WriteAsync($"Hello, {context.Request.RouteValues["name"]}!");
}
catch (Exception error)
{
// Report error to apitoolkit (associated with the request)
client.ReportError(context, error);
await context.Response.WriteAsync("Error reported!");
}
});

```
> To learn more about redacting fields, error reporting, outgoing requests, etc. please read our [.Net Core SDK](https://apitoolkit.io/docs/sdks/dotnet/dotnetcore/) documentation.
## Contributing and Help

Expand Down

0 comments on commit f986d96

Please sign in to comment.