Skip to content

Commit b2b0091

Browse files
Aaron Hedgesdomharrington
Aaron Hedges
authored and
domharrington
committed
update README.md to look more like ReadMe's standard metrics format
1 parent c2d0fdf commit b2b0091

File tree

1 file changed

+98
-50
lines changed

1 file changed

+98
-50
lines changed

‎README.md

+98-50
Original file line numberDiff line numberDiff line change
@@ -1,75 +1,123 @@
1+
# Readme.net
12

2-
# Overview
3-
The Metrics API gives you access to usage data for your API and hub, so you can make more data-driven decisions around your platform and API roadmap. Many of the metrics that you can get using this API are also available as visualizations directly in ReadMe in our Metrics charts.
3+
## Contents
4+
- [Overview](#overview)
5+
- [ASP.NET Core Integration](#aspnet-core-integration)
6+
- [ASP.NET Core Middleware Reference](#aspnet-core-middleware-reference)
47

5-
# Asp.Net Core Library Integration (3 steps)
6-
## 1. Installation
8+
## Overview
9+
With ReadMe's Metrics API your team can get deep insights into your API's usage. If you're a developer, it's super easy to send your API logs to ReadMe, Here's an overview of how the integration works:
710

8-
### In Visual Studio
9-
There are two ways to install the **Readme.Metrics** nuget package in your Asp.Net Core Web API / Asp.Net Core Web Application:-
11+
- Add the `Readme.Metrics` NuGet package to your API server and integrate the middleware.
12+
- The .NET SDK sends ReadMe the details of your API's incoming requests and outgoing responses, with the option for you to redact any private parameters or headers.
13+
- ReadMe uses these request and response details to create an API Metrics Dashboard which can be used to analyze specific API calls or monitor aggregate usage data. Additionally, if your users log into your API documentation we'll show them logs of the requests they made!
1014

11-
- By command
15+
## ASP.NET Core Integration
1216

13-
Open Package Manager Console by Tools => NuGet Package Manager => Package Manager Console and run below command
17+
1. Install the `Readme.Metrics` NuGet package using [Visual Studio, VS Code](https://docs.microsoft.com/en-us/nuget/install-nuget-client-tools) or the following command:
1418

15-
```c#
16-
Install-Package ReadMe.Metrics
17-
```
18-
- By GUI
19-
20-
Right click on project => Manage Nuget Packages => Browse. Here search Readme.Metrics package and install
19+
```shell
20+
dotnet add package Readme.Metrics
21+
```
2122

22-
### In Visual Studio Code
23-
Open new terminal and run below command
23+
2. Find the file that creates your `app`. This is often in a `Startup.cs` or `Program.cs` file depending on your version of .NET, and is located in your root directory. Find the `Configure` method, and add the following line before the routing is enabled. For full details on each option, read more about the [Group Object](#group-object).
2424

25-
```c#
26-
dotnet add package ReadMe.Metrics
27-
```
2825

29-
## 2. Integration
26+
```cs
27+
app.Use(async (context, next) =>
28+
{
29+
HttpRequest req = context.Request;
3030

31-
- ## In .Net 6
32-
Open **Program.cs** file in your Asp.Net Core Web API / Asp.Net Core Web Application and add below code under **var app = builder.Build();** line
33-
- ## In .Net 5 / .Net 3.1
34-
Locate and open **Startup.cs** file in your Asp.Net Core Web API / Asp.Net Core Web Application (Usually in root directory). Find Configure method and add below code at start:
31+
context.Items["apiKey"] = <Extract API users API key from the request>
32+
context.Items["label"] = <Extract API users display name from the request>
33+
context.Items["email"] = <Extract API users email address from the request>
3534

36-
```c#
37-
//Below middleware create items for group values
38-
//(apiKey, label, email)
35+
await next();
36+
});
37+
```
3938

40-
app.Use(async (context, next) =>
41-
{
42-
//You can extract apikey from request header by key like authentication, x-api-key as
43-
// context.Request.Headers["key"];
4439

45-
//Or extract apikey from request body form or x-www-form-urlencoded by key as
46-
// context.Request.Form["key"];
40+
3. Add the logging middleware to your API server. This will be added immediately after your custom middleware from step 2.
4741

48-
context.Items["apiKey"] = context.Request.Headers["key"];
49-
context.Items["label"] = "username / company name";
50-
context.Items["email"] = "email";
42+
```cs
43+
app.UseMiddleware<Readme.Metrics>();
44+
```
5145

52-
await next();
53-
});
54-
//Below middleware will invoke metrics library
55-
app.UseMiddleware<Readme.Metrics>();
56-
```
5746

58-
## 3. Global Configuration
59-
Locate the file **appsettings.json** in the root directory of Asp.Net Core Web API / Asp.Net Core Web Application. Copy and paste below code inside root curly brace. Fill properties with valid values.
47+
4. Locate `appsettings.json` in the root directory of your Application. Add the following JSON to your configuration and fill in any applicable values. For full details on each option read more about the [ReadMe Object in appsettings.json](readme-object-in-appsettingsjson)
6048

61-
```json
49+
```javascript
6250
"readme": {
63-
"apiKey": "Readme API Key",
51+
"apiKey": "<Your Readme API Key>",
52+
"options": {
53+
"allowList": [ "<Any parameters you want allowed in your log. See docs>" ],
54+
"denyList": [ "<Any parameters you want removed from your log. See docs>"],
55+
"development": true, // Where to bucket your data, development or production
56+
"baseLogUrl": "https://example.readme.com" // Your ReadMe website's base url
57+
}
58+
}
59+
```
60+
61+
For a full example take a look at our example project: https://github.com/readmeio/metrics-sdks-dotnet/blob/6794e99c86e608f90a8e6c6d1357bd73b4d1de75/RequestResponseLoggingMiddlewareAPI/Startup.cs#L23
62+
63+
## ASP.NET Core Middleware Reference
64+
### Group Object
65+
Before assigning the `Readme.Metrics` middleware you should assign custom middleware to extract certain grouping parameters, as seen in step 2 of the [ASP.NET Core Integration](aspnet-core-integration). The grouping parameters includes three values: `apiKey`, `label` and `email`. While only `apiKey` is required, we recommend providing all three values to get the most out of the metrics dashboard.
66+
67+
Field | Required? | Type | Usage
68+
-------|-----------|--------|------------
69+
`apiKey` | yes | string | API Key used to make the request. Note that this is different from the `readmeAPIKey` described above and should be a value from your API that is unique to each of your users, not part of ReadMe's API.
70+
`label` | no | string | This will be the users' display name in the API Metrics Dashboard, as it's much easier to remember a name than an API key.
71+
`email` | no | string | Email of the user that is making the call.
72+
73+
Example:
74+
75+
```cs
76+
app.Use(async (context, next) =>
77+
{
78+
HttpRequest req = context.Request;
79+
80+
context.Items["apiKey"] = <Extract API users API key from the request>
81+
context.Items["label"] = <Extract API users display name from the request>
82+
context.Items["email"] = <Extract API users email address from the request>
83+
84+
await next();
85+
});
86+
```
87+
88+
### ReadMe Object in appsettings.json
89+
The ASP.NET Core middleware extracts the following parameters from appsettings.json file:
90+
91+
`Parameter` | Required? | Description
92+
---------------|-----------|------------------
93+
`readmeAPIKey` | yes | The API key for your ReadMe project. This ensures your requests end up in your dashboard. You can read more about the API key in [our docs](https://docs.readme.com/reference/authentication).
94+
`options` | no | Additional options. You can read more under [Additional Express Options](#additional-express-options)
95+
96+
97+
#### Options Object
98+
This is an optional object used to restrict traffic being sent to readme server based on given values in allowList or denyList arrays.
99+
100+
`Option` | Type | Description
101+
------------|------------------|---------------
102+
`denyList` | Array of strings | An array of parameter names that will be redacted from the query parameters, request body (when JSON or form-encoded), response body (when JSON) and headers. For nested request parameters use dot notation (e.g. `a.b.c` to redact the field `c` within `{ a: { b: { c: 'foo' }}}`).
103+
`allowList` | Array of strings | If included, `denyList` will be ignored and all parameters but those in this list will be redacted.
104+
`development` | bool | Defaults to `false`. When `true`, the log will be marked as a development log. This is great for separating staging or test data from data coming from customers.
105+
`baseLogUrl` | string | This value is used when building the `x-documentation-url` header (see docs [below](#documentation-url)). It is your ReadMe documentation's base URL (e.g. `https://example.readme.com`). If not provided, we will make one API call a day to determine your base URL (more info in [Documentation URL](#documentation-url). If provided, we will use that value and never look it up automatically.
106+
107+
Example:
108+
```json
109+
{
110+
"apiKey": "abcd123",
64111
"options": {
65-
//"allowList" : ["username","address", "age"] means that library will extract values from headers,query strings and body whose key is given in allowList. When allowList is given, denyList will be ignored
66-
"allowList": [ ],
67-
//"denyList" : ["password","secret"] means that library will not extract values from headers,query strings and body whose key is given in denyList.
68-
"denyList": [ ],
112+
"denyList": ["password", "secret"],
69113
"development": true,
70114
"baseLogUrl": "https://example.readme.com"
71-
}
72115
}
116+
}
73117
```
74118

119+
### Documentation URL
120+
With the middleware loaded, all requests that funneled through it will receive a `x-documentation-url` header applied to the response. The value of this header will be the URL on ReadMe Metrics with which you can view the log for that request.
121+
122+
Make sure to supply a `baseLogUrl` option into your readme settings, which should evaluate to the public-facing URL of your ReadMe project.
75123

0 commit comments

Comments
 (0)