Skip to content

Commit c984acb

Browse files
chore(docs): add undocumented parameters to readme
1 parent e4ce03d commit c984acb

File tree

1 file changed

+113
-0
lines changed

1 file changed

+113
-0
lines changed

README.md

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -277,6 +277,119 @@ OrbClient client = new() { HttpClient = httpClient };
277277

278278
The SDK is typed for convenient usage of the documented API. However, it also supports working with undocumented or not yet supported parts of the API.
279279

280+
### Parameters
281+
282+
To set undocumented parameters, a constructor exists that accepts dictionaries for additional header, query, and body values. If the method type doesn't support request bodies (e.g. `GET` requests), the constructor will only accept a header and query dictionary.
283+
284+
```csharp
285+
using System.Collections.Generic;
286+
using System.Text.Json;
287+
using Orb.Models.Customers;
288+
289+
CustomerCreateParams parameters = new
290+
(
291+
rawHeaderData: new Dictionary<string, JsonElement>()
292+
{
293+
{ "Custom-Header", JsonSerializer.SerializeToElement(42) }
294+
},
295+
296+
rawQueryData: new Dictionary<string, JsonElement>()
297+
{
298+
{ "custom_query_param", JsonSerializer.SerializeToElement(42) }
299+
},
300+
301+
rawBodyData: new Dictionary<string, JsonElement>()
302+
{
303+
{ "custom_body_param", JsonSerializer.SerializeToElement(42) }
304+
}
305+
)
306+
{
307+
// Documented properties can still be added here.
308+
// In case of conflict, these parameters take precedence over the custom parameters.
309+
AutoCollection = true
310+
};
311+
```
312+
313+
The raw parameters can also be accessed through the `RawHeaderData`, `RawQueryData`, and `RawBodyData` (if available) properties.
314+
315+
This can also be used to set a documented parameter to an undocumented or not yet supported _value_, as long as the parameter is optional. If the parameter is required, omitting its `init` property will result in a compile-time error. To work around this, the `FromRawUnchecked` method can be used:
316+
317+
```csharp
318+
using System.Collections.Generic;
319+
using System.Text.Json;
320+
using Orb.Models.Customers;
321+
322+
var parameters = CustomerCreateParams.FromRawUnchecked
323+
(
324+
325+
rawHeaderData: new Dictionary<string, JsonElement>(),
326+
rawQueryData: new Dictionary<string, JsonElement>(),
327+
rawBodyData: new Dictionary<string, JsonElement>
328+
{
329+
{
330+
"email",
331+
JsonSerializer.SerializeToElement("custom value")
332+
}
333+
}
334+
);
335+
```
336+
337+
### Nested Parameters
338+
339+
Undocumented properties, or undocumented values of documented properties, on nested parameters can be set similarly, using a dictionary in the constructor of the nested parameter.
340+
341+
```csharp
342+
using System.Collections.Generic;
343+
using System.Text.Json;
344+
using Orb.Models.Customers;
345+
346+
CustomerCreateParams parameters = new()
347+
{
348+
AccountingSyncConfiguration = new
349+
(
350+
new Dictionary<string, JsonElement>
351+
{
352+
{ "custom_nested_param", JsonSerializer.SerializeToElement(42) }
353+
}
354+
)
355+
};
356+
```
357+
358+
Required properties on the nested parameter can also be changed or omitted using the `FromRawUnchecked` method:
359+
360+
```csharp
361+
using System.Collections.Generic;
362+
using System.Text.Json;
363+
using Orb.Models.Customers;
364+
365+
CustomerCreateParams parameters = new()
366+
{
367+
AccountingSyncConfiguration = NewAccountingSyncConfiguration.FromRawUnchecked
368+
(
369+
new Dictionary<string, JsonElement>
370+
{
371+
{ "required_property", JsonSerializer.SerializeToElement("custom value") }
372+
}
373+
)
374+
};
375+
```
376+
377+
### Response properties
378+
379+
To access undocumented response properties, the `RawData` property can be used:
380+
381+
```csharp
382+
using System.Text.Json;
383+
384+
var response = client.Customers.Create(parameters)
385+
if (response.RawData.TryGetValue("my_custom_key", out JsonElement value))
386+
{
387+
// Do something with `value`
388+
}
389+
```
390+
391+
`RawData` is a `IReadonlyDictionary<string, JsonElement>`. It holds the full data received from the API server.
392+
280393
### Response validation
281394

282395
In rare cases, the API may return a response that doesn't match the expected type. For example, the SDK may expect a property to contain a `string`, but the API could return something else.

0 commit comments

Comments
 (0)