Skip to content

Commit 3380167

Browse files
committed
Add some examples around heterogeneous primary resource bodies.
1 parent 5c3c8fd commit 3380167

File tree

1 file changed

+10
-1
lines changed

1 file changed

+10
-1
lines changed

documentation/usage.md

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -335,10 +335,19 @@ A JSON API Document is guaranteed by the **SPEC** to be "data", "metadata", or "
335335

336336
#### `ResourceBody`
337337

338-
The first generic type of a `JSONAPI.Document` is a `ResourceBody`. This can either be a `SingleResourceBody<PrimaryResource>` or a `ManyResourceBody<PrimaryResource>`. You will find zero or one `PrimaryResource` values in a JSON API document that has a `SingleResourceBody` and you will find zero or more `PrimaryResource` values in a JSON API document that has a `ManyResourceBody`. You can use the `Poly` types (`Poly1` through `Poly6`) to specify that a `ResourceBody` will be one of a few different types of `ResourceObject`. These `Poly` types work in the same way as the `Include` types described below.
338+
The first generic type of a `JSONAPI.Document` is a `ResourceBody`. This can either be a `SingleResourceBody<PrimaryResource>` or a `ManyResourceBody<PrimaryResource>`. You will find zero or one `PrimaryResource` values in a JSON API document that has a `SingleResourceBody` and you will find zero or more `PrimaryResource` values in a JSON API document that has a `ManyResourceBody`. You can use the `Poly` types (`Poly1` through `Poly11`) to specify that a `ResourceBody` will be one of a few different types of `ResourceObject`. These `Poly` types work in the same way as the `Include` types described below.
339339

340340
If you expect a response to not have a "data" top-level key at all, then use `NoResourceBody` instead.
341341

342+
Examples:
343+
```swift
344+
typealias SingleDog = JSONAPI.Document<SingleResourceBody<Dog>, NoMetadata, NoLinks, NoIncludes, BasicJSONAPIError<String>>
345+
346+
typealias ManyCats = JSONAPI.Document<ManyResourceBody<Cat>, NoMetadata, NoLinks, NoIncludes, BasicJSONAPIError<String>>
347+
348+
typealias ManyDogsOrCats = JSONAPI.Document<ManyResourceBody<Poly2<Dog, Cat>>, NoMetadata, NoLinks, NoIncludes, BasicJSONAPIError<String>>
349+
```
350+
342351
##### nullable `PrimaryResource`
343352

344353
If you expect a `SingleResourceBody` to sometimes come back `null`, you should make your `PrimaryResource` optional. If you do not make your `PrimaryResource` optional then a `null` primary resource will be considered an error when parsing the JSON.

0 commit comments

Comments
 (0)