Skip to content

Commit d14fcbb

Browse files
JustinTRossswalkinshaw
authored andcommitted
Fix typo, improve punctuation, and enforce consistency. (Shopify#7)
Commas were added and removed where there was impact to readability. Wording changes were made with the same intention. Mutation inputs using `id: ID!` were converted to `collectionId: ID!` to conform with other inputs in examples.
1 parent bcae3ca commit d14fcbb

File tree

1 file changed

+21
-21
lines changed

1 file changed

+21
-21
lines changed

TUTORIAL.md

Lines changed: 21 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -593,16 +593,16 @@ We now have a minimal but well-designed GraphQL API for collections. There is a
593593
lot of detail to collections that we haven't dealt with - any real
594594
implementation of this feature would need a lot more fields to deal with things
595595
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
597597
things which bear looking at in more detail.
598598

599599
For this section, it is most convenient to start with a motivating use case from
600600
the hypothetical client of our API. Let us therefore imagine that the client
601601
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
603603
something that the client can already answer with our existing API: we expose
604604
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.
606606

607607
This solution has two problems though. The first, obvious problem is that it's
608608
inefficient; collections can contain millions of products, and having the client
@@ -738,14 +738,14 @@ of factors to consider:
738738
- removeProducts
739739
- reorderProducts
740740

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
742742
and ordered. Rules we left inline because the relationship is small, and rules
743743
are sufficiently minor to not have IDs.
744744

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.
749749

750750
*Rule #16: When writing separate mutations for relationships, consider whether
751751
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:
778778

779779
```graphql
780780
type Mutation {
781-
collectionDelete(id: ID!)
781+
collectionDelete(collectionId: ID!)
782782
collectionPublish(collectionId: ID!)
783783
collectionUnpublish(collectionId: ID!)
784784
collectionAddProducts(collectionId: ID!, productIds: [ID!]!)
@@ -846,7 +846,7 @@ It is important to note, though, that this is not an invitation to weakly-type
846846
all your inputs. We still use strongly-typed enums for the `field` and
847847
`relation` values on our rule input, and we would still use strong typing for
848848
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
850850
ambiguity of the format. HTML is a well-defined, unambiguous specification, but
851851
is quite complex to validate. On the other hand, there are hundreds of ways to
852852
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:
865865
type Mutation {
866866
# ...
867867
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)
869869
}
870870
```
871871

872872
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.
878878

879879
While there are some arguments for leaving these mutations as-is, we have
880880
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:
892892
type Mutation {
893893
# ...
894894
collectionCreate(collection: CollectionInput!)
895-
collectionUpdate(id: ID!, collection: CollectionInput!)
895+
collectionUpdate(collectionId: ID!, collection: CollectionInput!)
896896
}
897897

898898
input CollectionInput {
@@ -933,14 +933,14 @@ type UserError {
933933

934934
Here, a successful mutation would return an empty list for `userErrors` and
935935
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.
938938

939939
*Rule #22: Mutations should provide user/business-level errors via a
940940
`userErrors` field on the mutation payload. The top-level query errors entry is
941941
reserved for client and server-level errors.*
942942

943-
In many implementations, much of this structure is provided automatically and
943+
In many implementations, much of this structure is provided automatically, and
944944
all you will have to define is the `collection` return field.
945945

946946
For the update mutation, we follow exactly the same pattern:
@@ -953,7 +953,7 @@ type CollectionUpdatePayload {
953953
```
954954

955955
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
957957
return.
958958

959959
*Rule #23: Most payload fields for a mutation should be nullable, unless there

0 commit comments

Comments
 (0)