This package adds support to ChilliCream's
HotChocolate for
polymorphic Relay / Global IDs so that you can pass the database id in as an ID in
an input/argument and it'll be accepted.
For example, if you read the description of an ID type in GitHub's GraphQL API, it says:
When expected as an input type, any string (such as "4") or integer (such as 4) input value will be accepted as an ID.
The following becomes possible (on args/input fields annotated with HotChocolate's [ID] attribute).
# Schema
type Query {
booking(id: ID!): Booking
}
# Query
query {
bookingByGlobalId: booking(id: "TheGlobalIdValue7sghdyg=") { ... }
bookingByDbId: booking(id: 1) { ... }
bookingByDbIdString: booking(id: "1") { ... }
}- To achieve friendly URLs, like
/booking/123, you need to be able to get a booking by its database id (123) as the client doesn't have the global ID. But it's nasty to have to expose abookingByDbId(id: Int!)field to do so. - For easier debugging. As humans we use database ids. So if you've got one, you can just pass it on through.
Currently only arguments / input fields that are annotated with the [ID] attribute will be noticed and have support added for handling different ids.
Specifically, the fluent-style declaration .ID() won't be handled right now; though support could
be added for it in the future so shout out if you need it on the open issue.
Arrays of IDs are handled (but only v2+ can support arrays of nullable IDs ([ID] or [ID]!) due to a bug in Hot Chocolate v11).
IDs that are internally represented with int, Guid, long or string, and their nullable equivalents will be handled.
You can opt-out of each's support as required.
For integer-based IDs, you can pass "1" or 1 and both will be accepted.
For all other types, you need to pass the string value, e.g.
"26a2dc8f-4dab-408c-88c6-523a0a89a2b5"for a guid-based ID"123456789"for a long-based ID
- Strings are a problem. It's difficult to distinguish between the global id format and a string database id. As such, in this case, we try to read it as a global id and if that throws we consider it a database id. The one problem being that invalid global ids, e.g. you missed one char, will be considered a database id. If you don't have string db ids, it's a good idea to just turn off their handling so an invalid global id would still throw (see setup below).
- There's a performance hit to the interception, but it'd be barely measurable.
- Once you go down this path, it's very difficult to go back as your clients will start to rely on this.
Install a compatible version of the package from NuGet
dotnet add package AutoGuru.HotChocolate.PolymorphicIdsConfigure it on your schema (ISchemaBuilder) or executor (IRequestExecutorBuilder):
.AddGlobalObjectIdentification() // Required since Hot Chocolate v12.6.0+
.AddPolymorphicIds(new PolymorphicIdsOptions
{
HandleGuidIds = false, // true by default
HandleIntIds = true, // true by default
HandleLongIds = false, // true by default
HandleStringIds = false, // true by default
});At AutoGuru we add a dbId field to all our nodes. Since this is essentially the same as declaring the node's id field, we've got
some helpers for this that can be found here.
Currently this is a manual/explicit thing you need to do, but in future this will ideally become automatic via a type interceptor if I can figure out how to get that to work (last attempt failed :P).
We depend on HotChocolate.Execution which can bring breaking changes from time to time and require a major bump our end. Compatibility is listed below.
We strive to match Hot Chocolate's supported .NET target frameworks, though this might not always be possible.
| HotChocolate | Polymorphic IDs | Our docs |
|---|---|---|
| v13.0.0 | v4 | right here |
| v12.6.0* | v3 | /v3/main branch |
| v12.0.0 | v2 | /v2/main branch |
| v11.1.0 | v1 | /v1/main branch |
* Denotes unexpected binary incompatibility / breaking change in Hot Chocolate
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent