Adding first draft of incremental delivery spec artifact (#67)

Co-authored-by: Martin Bonnin <[email protected]>

Author: calvincestari

__index__.md

@@ -19,6 +19,8 @@
 - **[federation/v2.9](/federation/v2.9)** ([📄 graphql](federation/v2.9/federation-v2.9.graphql))
 - **[inaccessible/v0.1](/inaccessible/v0.1)** ([📄 graphql](inaccessible/v0.1/inaccessible-v0.1.graphql))
 - **[inaccessible/v0.2](/inaccessible/v0.2)** ([📄 graphql](inaccessible/v0.2/inaccessible-v0.2.graphql))
+- **[incremental/v0.1](/incremental/v0.1)** ([📄 graphql](incremental/v0.1/incremental-v0.1.graphql))
+- **[incremental/v0.2](/incremental/v0.2)** ([📄 graphql](incremental/v0.2/incremental-v0.2.graphql))
 - **[join/v0.1](/join/v0.1)** ([📄 graphql](join/v0.1/join-v0.1.graphql))
 - **[join/v0.2](/join/v0.2)** ([📄 graphql](join/v0.2/join-v0.2.graphql))
 - **[join/v0.3](/join/v0.3)** ([📄 graphql](join/v0.3/join-v0.3.graphql))

incremental/v0.1/http.md

@@ -0,0 +1,7 @@
+# HTTP Request Headers
+
+In order for the server to know that the client can parse the incremental delivery response format, the HTTP request must include the following header:
+
+## Accept
+
+`multipart/mixed;deferSpec=20220824`

incremental/v0.1/incremental-v0.1.graphql

@@ -0,0 +1,34 @@
+"""
+Used to imply de-prioritization, that causes the fragment to be omitted in the initial response, and delivered as a subsequent response afterward.
+
+Arguments:
+* `if: Boolean`
+  * When `true` fragment may be deferred, if omitted defaults to `true`.
+* `label: String`
+  * A unique label across all `@defer` and `@stream` directives in an operation.
+  * This `label` should be used by GraphQL clients to identify the data from patch responses and associate it with the correct fragment.
+  * If provided, the GraphQL Server must add it to the payload.
+"""
+directive @defer(
+  label: String
+  if: Boolean! = true
+) on FRAGMENT_SPREAD | INLINE_FRAGMENT
+
+"""
+This directive may be provided for a field of `List` type so that the backend can leverage technology such asynchronous iterators to provide a partial list in the initial response, and additional list items in subsequent responses.
+
+Arguments:
+* `if: Boolean`
+  * When `true` field may be streamed, if omitted defaults to `true`.
+* `label: String`
+  * A unique label across all `@defer` and `@stream` directives in an operation.
+  * This `label` should be used by GraphQL clients to identify the data from patch responses and associate it with the correct fragments.
+  * If provided, the GraphQL Server must add it to the payload.
+* `initialCount: Int`
+  * The number of list items the server should return as part of the initial response.
+"""
+directive @stream(
+  label: String
+  if: Boolean! = true
+  initialCount: Int = 0
+) on FIELD

incremental/v0.1/incremental-v0.1.md

@@ -0,0 +1,7 @@
+# HTTP Request Headers
+
+In order for the server to know that the client can parse the incremental delivery response format, the HTTP request must include the following header:
+
+## Accept
+
+`multipart/mixed;incrementalSpec=v0.2`

incremental/v0.2/http.md

@@ -0,0 +1,34 @@
+"""
+Used to imply de-prioritization, that causes the fragment to be omitted in the initial response, and delivered as a subsequent response afterward.
+
+Arguments:
+* `if: Boolean`
+  * When `true` fragment may be deferred, if omitted defaults to `true`.
+* `label: String`
+  * A unique label across all `@defer` and `@stream` directives in an operation.
+  * This `label` should be used by GraphQL clients to identify the data from patch responses and associate it with the correct fragment.
+  * If provided, the GraphQL Server must add it to the payload.
+"""
+directive @defer(
+  label: String
+  if: Boolean! = true
+) on FRAGMENT_SPREAD | INLINE_FRAGMENT
+
+"""
+This directive may be provided for a field of `List` type so that the backend can leverage technology such asynchronous iterators to provide a partial list in the initial response, and additional list items in subsequent responses.
+
+Arguments:
+* `if: Boolean`
+  * When `true` field may be streamed, if omitted defaults to `true`.
+* `label: String`
+  * A unique label across all `@defer` and `@stream` directives in an operation.
+  * This `label` should be used by GraphQL clients to identify the data from patch responses and associate it with the correct fragments.
+  * If provided, the GraphQL Server must add it to the payload.
+* `initialCount: Int`
+  * The number of list items the server should return as part of the initial response.
+"""
+directive @stream(
+  label: String
+  if: Boolean! = true
+  initialCount: Int = 0
+) on FIELD

incremental/v0.2/incremental-v0.2.graphql

@@ -19,6 +19,10 @@
 
 [federation v2.9](/federation/v2.9) provides graph composition primitives for use in subgraphs.
 
+## incremental v0.2
+
+[incremental v0.2](/incremental/v0.2) provides specification and client usage details for the response format used with the {@defer} and {@stream} directives.
+
 ## join v0.3
 
 [join v0.3](/join/v0.3) declaratively describes joins between types in a supergraph.