Skip to content

Commit 2a47243

Browse files
Copilotbastianeicher
Copilot
and
bastianeicher
committed
Distribute serializer content into separate json.md, xml.md, and bson.md files
Co-authored-by: bastianeicher <414366+bastianeicher@users.noreply.github.com>
1 parent 33ed38c commit 2a47243

6 files changed

Lines changed: 222 additions & 112 deletions

File tree

‎docs/link-handling/.pages‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,4 +4,3 @@ nav:
44
- uri-templates.md
55
- link-header.md
66
- hal.md
7-
- serializers.md

‎docs/serializers/.pages‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,3 +2,4 @@ nav:
22
- index.md
33
- json.md
44
- xml.md
5+
- bson.md

‎docs/serializers/bson.md‎

Lines changed: 31 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,31 @@
1-
# BSON serializers
1+
# BSON
2+
3+
BSON (Binary JSON) serialization is available in the .NET implementation of TypedRest.
4+
5+
## .NET
6+
7+
The BSON serializer provides efficient binary serialization using Newtonsoft.Json's BSON support:
8+
9+
=== "C#"
10+
11+
```csharp
12+
using TypedRest.Serializers;
13+
14+
var serializer = new BsonSerializer();
15+
var endpoint = new EntryEndpoint(
16+
new Uri("http://example.com/"),
17+
serializer: serializer);
18+
```
19+
20+
The BSON serializer uses the same Newtonsoft.Json settings as the default JSON serializer:
21+
22+
- Camel-case property naming
23+
- String enums with camel-case naming
24+
- Null values are not serialized
25+
- Automatic type name handling
26+
27+
The serializer handles the `application/bson` content type.
28+
29+
## TypeScript
30+
31+
BSON serialization is not supported in the TypeScript implementation. Use JSON serialization instead.

‎docs/serializers/index.md‎

Lines changed: 41 additions & 108 deletions
Original file line numberDiff line numberDiff line change
@@ -12,134 +12,67 @@ Serializers control how entities are serialized when sending requests and deseri
1212
| XML | ✅ | ❌ |
1313
| BSON | ✅ | ❌ |
1414

15-
## .NET Serializers
15+
## Serializer Types
1616

17-
### JSON with Newtonsoft.Json (Default)
17+
### [JSON](json.md)
1818

19-
The default serializer uses Newtonsoft.Json with the following settings:
19+
JSON is the default serialization format in both TypedRest implementations:
2020

21-
- Camel-case property naming
22-
- String enums with camel-case naming
23-
- Null values are not serialized
24-
- Automatic type name handling
21+
- **.NET**: Uses [Newtonsoft.Json](https://www.newtonsoft.com/json) by default, with optional support for System.Text.Json via a separate NuGet package
22+
- **TypeScript**: Uses native `JSON.stringify()` and `JSON.parse()`
2523

26-
```csharp
27-
var endpoint = new EntryEndpoint(new Uri("http://example.com/"));
28-
// Uses NewtonsoftJsonSerializer by default
29-
```
24+
Both implementations automatically handle custom JSON media types with the `+json` suffix (e.g., `application/vnd.api+json`, `application/hal+json`).
3025

31-
To customize:
26+
### [XML](xml.md)
3227

33-
```csharp
34-
var serializer = new NewtonsoftJsonSerializer();
35-
serializer.SerializerSettings.DateFormatString = "yyyy-MM-dd";
28+
XML serialization is available in .NET using the built-in `System.Xml.Serialization.XmlSerializer`. TypeScript does not support XML serialization.
3629

37-
var endpoint = new EntryEndpoint(new Uri("http://example.com/"), serializer: serializer);
38-
```
30+
### [BSON](bson.md)
3931

40-
### JSON with System.Text.Json
32+
BSON (Binary JSON) serialization is available in .NET for efficient binary serialization. TypeScript does not support BSON serialization.
4133

42-
For better performance, you can use the System.Text.Json serializer from the `TypedRest.SystemTextJson` NuGet package:
34+
## Multiple Serializers
4335

44-
```bash
45-
dotnet add package TypedRest. SystemTextJson
46-
```
36+
In .NET, you can provide multiple serializers for content negotiation:
4737

48-
```csharp
49-
using TypedRest. Serializers;
38+
=== "C#"
5039

51-
var serializer = new SystemTextJsonSerializer();
52-
var endpoint = new EntryEndpoint(new Uri("http://example.com/"), serializer: serializer);
53-
```
40+
```csharp
41+
var serializers = new MediaTypeFormatter[]
42+
{
43+
new SystemTextJsonSerializer(),
44+
new XmlSerializer()
45+
};
5446

55-
Default settings:
47+
var endpoint = new EntryEndpoint(httpClient, serializers);
48+
```
5649

57-
- Web defaults (camel-case property naming)
58-
- Null values are not serialized when writing
50+
The first serializer is used for outgoing requests. For incoming responses, the appropriate serializer is selected based on the `Content-Type` header.
5951

60-
To customize:
52+
## Serializer Inheritance
6153

62-
```csharp
63-
var serializer = new SystemTextJsonSerializer();
64-
serializer.Options.WriteIndented = true;
65-
serializer.Options.Converters.Add(new JsonStringEnumConverter());
66-
```
54+
When creating child endpoints, the serializer configuration is automatically inherited from the parent (referrer) endpoint:
6755

68-
### XML
56+
=== "C#"
6957

70-
For XML serialization:
58+
```csharp
59+
var client = new EntryEndpoint(new Uri("http://example.com/"));
60+
client.Serializer = new SystemTextJsonSerializer();
7161

72-
```csharp
73-
using TypedRest. Serializers;
62+
// Child endpoints inherit the serializer
63+
var contacts = new CollectionEndpoint<Contact>(client, relativeUri: "./contacts");
64+
// contacts.Serializer is automatically set to the same SystemTextJsonSerializer
65+
```
7466

75-
var serializer = new XmlSerializer();
76-
var endpoint = new EntryEndpoint(new Uri("http://example.com/"), serializer: serializer);
77-
```
67+
=== "TypeScript"
7868

79-
### BSON
69+
```typescript
70+
const client = new EntryEndpoint(new URL("http://example.com/"));
71+
client.serializer = new CustomSerializer();
8072

81-
For BSON (Binary JSON) serialization:
73+
// Child endpoints inherit the serializer
74+
const contacts = new CollectionEndpoint<Contact>(client, "./contacts");
75+
// contacts.serializer is automatically set to the same CustomSerializer
76+
```
8277

83-
```csharp
84-
using TypedRest.Serializers;
85-
86-
var serializer = new BsonSerializer();
87-
var endpoint = new EntryEndpoint(new Uri("http://example.com/"), serializer: serializer);
88-
```
89-
90-
BSON uses the same Newtonsoft.Json settings as the default JSON serializer.
91-
92-
### Multiple Serializers
93-
94-
You can provide multiple serializers for content negotiation:
95-
96-
```csharp
97-
var serializers = new MediaTypeFormatter[]
98-
{
99-
new SystemTextJsonSerializer(),
100-
new XmlSerializer()
101-
};
102-
103-
var endpoint = new EntryEndpoint(httpClient, serializers);
104-
```
105-
106-
The first serializer is used for outgoing requests. For incoming responses, the appropriate serializer is selected based on the `Content-Type` header.
107-
108-
## TypeScript Serializers
109-
110-
### JSON (Default)
111-
112-
TypeScript uses the native `JSON. stringify()` and `JSON.parse()` methods:
113-
114-
```typescript
115-
const endpoint = new EntryEndpoint(new URL("http://example.com/"));
116-
// Uses JsonSerializer by default
117-
```
118-
119-
### Custom Serializers
120-
121-
You can implement the `Serializer` interface for custom serialization:
122-
123-
```typescript
124-
import { Serializer } from "typedrest";
125-
126-
class MySerializer implements Serializer {
127-
readonly supportedMediaTypes = ["application/json"];
128-
129-
serialize<T>(entity: T): string {
130-
// Custom serialization logic
131-
return JSON.stringify(entity);
132-
}
133-
134-
deserialize<T>(text: string): T {
135-
// Custom deserialization logic
136-
return JSON. parse(text) as T;
137-
}
138-
}
139-
140-
const endpoint = new EntryEndpoint(new URL("http://example.com/"), new MySerializer());
141-
```
142-
143-
## Custom JSON Media Types
144-
145-
Both .NET and TypeScript automatically handle custom media types that end with `+json` (e.g., `application/vnd.api+json`). These are treated as JSON and deserialized using the configured JSON serializer.
78+
This inheritance ensures consistent serialization behavior across your entire endpoint hierarchy.

‎docs/serializers/json.md‎

Lines changed: 122 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,122 @@
1-
# JSON serializers
1+
# JSON
2+
3+
JSON is the default serialization format in both TypedRest implementations. Different JSON libraries are used depending on the platform and your preferences.
4+
5+
## .NET
6+
7+
### Newtonsoft.Json (Default)
8+
9+
The default serializer uses [Newtonsoft.Json](https://www.newtonsoft.com/json) with the following settings:
10+
11+
- Camel-case property naming
12+
- String enums with camel-case naming
13+
- Null values are not serialized
14+
- Automatic type name handling
15+
16+
=== "C#"
17+
18+
```csharp
19+
var endpoint = new EntryEndpoint(new Uri("http://example.com/"));
20+
// Uses NewtonsoftJsonSerializer by default
21+
```
22+
23+
To customize the serializer settings:
24+
25+
=== "C#"
26+
27+
```csharp
28+
var serializer = new NewtonsoftJsonSerializer();
29+
serializer.SerializerSettings.DateFormatString = "yyyy-MM-dd";
30+
31+
var endpoint = new EntryEndpoint(
32+
new Uri("http://example.com/"),
33+
serializer: serializer);
34+
```
35+
36+
### System.Text.Json
37+
38+
For better performance, you can use the System.Text.Json serializer from the `TypedRest.SystemTextJson` NuGet package:
39+
40+
=== "C#"
41+
42+
```bash
43+
dotnet add package TypedRest.SystemTextJson
44+
```
45+
46+
!!! note
47+
The `TypedRest.SystemTextJson` package version should match your main `TypedRest` package version. Both packages follow the same versioning scheme.
48+
49+
Default settings:
50+
51+
- Web defaults (camel-case property naming)
52+
- Null values are not serialized when writing
53+
54+
Basic usage:
55+
56+
=== "C#"
57+
58+
```csharp
59+
using TypedRest.Serializers;
60+
61+
var serializer = new SystemTextJsonSerializer();
62+
var endpoint = new EntryEndpoint(
63+
new Uri("http://example.com/"),
64+
serializer: serializer);
65+
```
66+
67+
To customize the serializer options:
68+
69+
=== "C#"
70+
71+
```csharp
72+
var serializer = new SystemTextJsonSerializer();
73+
serializer.Options.WriteIndented = true;
74+
serializer.Options.Converters.Add(new JsonStringEnumConverter());
75+
76+
var endpoint = new EntryEndpoint(
77+
new Uri("http://example.com/"),
78+
serializer: serializer);
79+
```
80+
81+
## TypeScript
82+
83+
TypeScript uses the native `JSON.stringify()` and `JSON.parse()` methods:
84+
85+
=== "TypeScript"
86+
87+
```typescript
88+
const endpoint = new EntryEndpoint(new URL("http://example.com/"));
89+
// Uses JsonSerializer by default
90+
```
91+
92+
### Custom Serializers
93+
94+
You can implement the `Serializer` interface for custom serialization:
95+
96+
=== "TypeScript"
97+
98+
```typescript
99+
import { Serializer } from "typedrest";
100+
101+
class MySerializer implements Serializer {
102+
readonly supportedMediaTypes = ["application/json"];
103+
104+
serialize<T>(entity: T): string {
105+
// Custom serialization logic
106+
return JSON.stringify(entity);
107+
}
108+
109+
deserialize<T>(text: string): T {
110+
// Custom deserialization logic
111+
return JSON.parse(text) as T;
112+
}
113+
}
114+
115+
const endpoint = new EntryEndpoint(
116+
new URL("http://example.com/"),
117+
new MySerializer());
118+
```
119+
120+
## Custom JSON Media Types
121+
122+
Both .NET and TypeScript automatically handle custom media types that end with `+json` (e.g., `application/vnd.api+json`, `application/hal+json`). These are treated as JSON and deserialized using the configured JSON serializer.

‎docs/serializers/xml.md‎

Lines changed: 27 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,27 @@
1-
# XML serializers
1+
# XML
2+
3+
XML serialization is available in the .NET implementation of TypedRest.
4+
5+
## .NET
6+
7+
The XML serializer uses .NET's built-in `System.Xml.Serialization.XmlSerializer`:
8+
9+
=== "C#"
10+
11+
```csharp
12+
using TypedRest.Serializers;
13+
14+
var serializer = new XmlSerializer();
15+
var endpoint = new EntryEndpoint(
16+
new Uri("http://example.com/"),
17+
serializer: serializer);
18+
```
19+
20+
The serializer handles the following content types:
21+
22+
- `application/xml`
23+
- `text/xml`
24+
25+
## TypeScript
26+
27+
XML serialization is not supported in the TypeScript implementation. Use JSON serialization instead.

0 commit comments

Comments
 (0)