@@ -593,16 +593,16 @@ We now have a minimal but well-designed GraphQL API for collections. There is a
593
593
lot of detail to collections that we haven't dealt with - any real
594
594
implementation of this feature would need a lot more fields to deal with things
595
595
like product sort order, publishing, etc. - but as a rule those fields will all
596
- follow the same design patterns layed out here. However, there are still a few
596
+ follow the same design patterns laid out here. However, there are still a few
597
597
things which bear looking at in more detail.
598
598
599
599
For this section, it is most convenient to start with a motivating use case from
600
600
the hypothetical client of our API. Let us therefore imagine that the client
601
601
developer we have been working with needs to know something very specific:
602
- whether a given product is a member of a collection or not. Of course this is
602
+ whether a given product is a member of a collection or not. Of course, this is
603
603
something that the client can already answer with our existing API: we expose
604
604
the complete set of products in a collection, so the client simply has to
605
- iterate through looking for the product they care about.
605
+ iterate through, looking for the product they care about.
606
606
607
607
This solution has two problems though. The first, obvious problem is that it's
608
608
inefficient; collections can contain millions of products, and having the client
@@ -738,14 +738,14 @@ of factors to consider:
738
738
- removeProducts
739
739
- reorderProducts
740
740
741
- Products we split into their own mutations, because the relationship is large,
741
+ Products we split into their own mutations, because the relationship is large
742
742
and ordered. Rules we left inline because the relationship is small, and rules
743
743
are sufficiently minor to not have IDs.
744
744
745
- Finally, you may note that we have mutations like `addProducts` and not
746
- `addProduct`. This is simply a convenience for the client, since the common use
747
- case when manipulating this relationship will be to add, remove, or reorder more
748
- than one product at a time.
745
+ Finally, you may note our product mutations act on sets of products, for example
746
+ `addProducts` and not ` addProduct`. This is simply a convenience for the client,
747
+ since the common use case when manipulating this relationship will be to add,
748
+ remove, or reorder more than one product at a time.
749
749
750
750
*Rule #16: When writing separate mutations for relationships, consider whether
751
751
it would be useful for the mutations to operate on multiple elements at once.*
@@ -778,7 +778,7 @@ we can start with something like this:
778
778
779
779
```graphql
780
780
type Mutation {
781
- collectionDelete (id : ID !)
781
+ collectionDelete (collectionId : ID !)
782
782
collectionPublish (collectionId : ID !)
783
783
collectionUnpublish (collectionId : ID !)
784
784
collectionAddProducts (collectionId : ID !, productIds : [ID !]!)
@@ -846,7 +846,7 @@ It is important to note, though, that this is not an invitation to weakly-type
846
846
all your inputs . We still use strongly -typed enums for the `field ` and
847
847
`relation ` values on our rule input , and we would still use strong typing for
848
848
certain other inputs like `DateTime `s if we had any in this example . The key
849
- differentiating factors are the complexity of client -side validation , and the
849
+ differentiating factors are the complexity of client -side validation and the
850
850
ambiguity of the format . HTML is a well -defined , unambiguous specification , but
851
851
is quite complex to validate . On the other hand , there are hundreds of ways to
852
852
represent a date or time as a string , all of them reasonably simple , so it
@@ -865,16 +865,16 @@ Continuing on to the update mutation, it might look something like this:
865
865
type Mutation {
866
866
# ...
867
867
collectionCreate (title : String ! , ruleSet : CollectionRuleSetInput , image : ImageInput , description : String )
868
- collectionUpdate (id : ID ! , title : String , ruleSet : CollectionRuleSetInput , image : ImageInput , description : String )
868
+ collectionUpdate (collectionId : ID ! , title : String , ruleSet : CollectionRuleSetInput , image : ImageInput , description : String )
869
869
}
870
870
```
871
871
872
872
You 'll note that this is very similar to our create mutation , with two
873
- differences : an ` id ` argument was added which determines which collection to
874
- update , and `title ` is no longer required since the collection must already have
875
- one . Ignoring the title 's required status for a moment our example mutations
876
- have four duplicate arguments , and a complete collections model would include
877
- quite a few more .
873
+ differences : a ` collectionId ` argument was added , which determines which
874
+ collection to update , and `title ` is no longer required since the collection
875
+ must already have one . Ignoring the title 's required status for a moment , our
876
+ example mutations have four duplicate arguments , and a complete collections
877
+ model would include quite a few more .
878
878
879
879
While there are some arguments for leaving these mutations as -is , we have
880
880
decided that situations like this call for DRYing up the common portions of the
@@ -892,7 +892,7 @@ the title is required on creation. Our schema ends up looking like this:
892
892
type Mutation {
893
893
# ...
894
894
collectionCreate (collection : CollectionInput !)
895
- collectionUpdate (id : ID !, collection : CollectionInput !)
895
+ collectionUpdate (collectionId : ID !, collection : CollectionInput !)
896
896
}
897
897
898
898
input CollectionInput {
@@ -933,14 +933,14 @@ type UserError {
933
933
934
934
Here , a successful mutation would return an empty list for `userErrors ` and
935
935
would return the newly -created collection for the `collection ` field . An
936
- unsuccessful one would return one or more `UserError ` objects , and null for the
937
- collection .
936
+ unsuccessful mutation would return one or more `UserError ` objects , and ` null `
937
+ for the collection .
938
938
939
939
*Rule #22: Mutations should provide user/business-level errors via a
940
940
`userErrors ` field on the mutation payload . The top -level query errors entry is
941
941
reserved for client and server -level errors .*
942
942
943
- In many implementations , much of this structure is provided automatically and
943
+ In many implementations , much of this structure is provided automatically , and
944
944
all you will have to define is the `collection ` return field .
945
945
946
946
For the update mutation , we follow exactly the same pattern :
@@ -953,7 +953,7 @@ type CollectionUpdatePayload {
953
953
```
954
954
955
955
It 's worth noting that `collection ` is still nullable even here , since if the
956
- provided ID doesn 't represent a valid collection there is no collection to
956
+ provided ID doesn 't represent a valid collection , there is no collection to
957
957
return .
958
958
959
959
*Rule #23: Most payload fields for a mutation should be nullable, unless there
0 commit comments