|
|
(29 intermediate revisions by the same user not shown) |
Line 1: |
Line 1: |
| [[graphql]] gem for ruby. | | [[graphql]] gem for ruby. |
|
| |
| {{ NOTE |
| |
| needs revisiting }}
| |
|
| |
|
| = Documentation = | | = Documentation = |
Line 21: |
Line 18: |
| </blockquote><!-- Documentation --> | | </blockquote><!-- Documentation --> |
|
| |
|
| = Basics = | | = Notes = |
| <blockquote> | | <blockquote> |
| Read [[graphql]] to get a general understanding of how graphql works before reading this.
| | {| class="wikitable" |
| | |- |
| | | [[graphql-ruby basics]] |
| | |- |
| | | [[graphql-ruby setup]] |
| | |- |
| | | [[graphql-ruby usage]] |
| | |- |
| | | [[graphql-ruby datatypes]] |
| | |- |
| | | [[graphql-ruby errors]] |
| | |- |
| | |} |
| | </blockquote><!-- Notes --> |
|
| |
|
| == Schema == | | = GraphQL Syntax = |
| <blockquote> | | <blockquote> |
| * schemas are assigned a root object for queries(queryable object), and optionally mutations(operations with side effects).
| | {| class="wikitable" |
| * objects expose fields(objects) which can have arguments
| | |- |
| * fields/arguments (exposed methods) are written in snake_case, but converted to camelCase when used in queries.
| | | [[graphql-ruby objects]] |
| | | |- |
| <source lang="ruby">
| | | [[graphql-ruby queries]] |
| class MySchema < GraphQL::Schema
| | |- |
| mutation(MyMutationType) # fields on MyMutationType accessible to schema
| | | [[graphql-ruby mutations]] |
| query(MyQueryType) # fields on MyQueryType accessible to schema
| | |- |
| # ...
| | | [[graphql-ruby relationships]] |
| end
| | |- |
| | | | [[graphql-ruby subscriptions]] |
| class MyQueryType
| | |- |
| end
| | |} |
| | | </blockquote><!-- GraphQL Syntax --> |
| class MyMutationType
| |
| end
| |
| </source>
| |
| </blockquote><!-- schema --> | |
|
| |
|
| == Queries(objects) == | | = Graphql-Ruby Feature Syntax = |
| <blockquote> | | <blockquote> |
| {| class="wikitable" | | {| class="wikitable" |
| |- | | |- |
| | field docs || https://graphql-ruby.org/fields/introduction | | | [[graphql-ruby connections]] |
| | |- |
| | | [[graphql-ruby authorization]] |
| | |- |
| | | [[graphql-ruby dataloader]] |
| |- | | |- |
| | field arg docs || https://graphql-ruby.org/fields/arguments | | | [[graphql-ruby testing]] |
| |- | | |- |
| |} | | |} |
| | | </blockquote><!-- Custom Syntax --> |
| {{ TODO |
| |
| split this example into multiple examples to more clearly describe one concept at a time
| |
| }}
| |
| | |
| Objects are described heirarchically starting with a single/root <code>GraphApi::ObjectType</code> which exposes other <code>GraphApi::ObjectType</code> objects as '''fields'''<br>
| |
| This root object is assigned to the schema using it's method <code>query(YourObject)</code>.
| |
| | |
| <source lang="ruby">
| |
| class MyGraph < GraphQL::Schema::ObjectType
| |
| | |
| # ==========
| |
| # user query
| |
| # ==========
| |
| field :user, User do |field|
| |
| field.argument(:name, String, required: true, description: "...")
| |
| field.argument(:family, FamilyType)
| |
| end
| |
| | |
| def user(name, family)
| |
| User.find_by(
| |
| firstname: name,
| |
| lastname: family[:last_name], # fields from input graphql types accessible as snake_cased hash-keys
| |
| )
| |
| end
| |
| | |
| # =============
| |
| # project query
| |
| # =============
| |
| field :projectDetails, ProjectDetailsType
| |
| | |
| def project
| |
| # you may return a hash with keys satisfying return-type
| |
| { name: "myproject", foo: "bar" }
| |
| end
| |
| end
| |
| | |
| class FamilyType
| |
| field :lastName, String # fields expected in camelCase
| |
| end
| |
| | |
| class User < GraphQL::Schema::ObjectType
| |
| field # ...
| |
| end
| |
| | |
| class ProjectDetailsType < GraphQL::Schema::ObjectType
| |
| field :name, String
| |
| field :foo, String
| |
| end
| |
| </source>
| |
| </blockquote><!-- queries --> | |
| | |
| == Mutations ==
| |
| <blockquote>
| |
| Mutations perform jobs with side-effects (like POST, PATCH, DELETE, ...)
| |
| <source lang="ruby">
| |
| class MyMutation < GraphQL::Schema::RelayClassicMutation
| |
| field :foo, String, null: false # exposes attribute 'foo', of type String, non-nullable
| |
| field :bar, String, null: true
| |
| | |
| argument :id, Integer, description: '...'
| |
| | |
| # method that runs when mutation is executed
| |
| def resolve(id)
| |
| return { foo: "abc", bar: "def" } # returns all fields defined on class
| |
| end
| |
| end
| |
| </source>
| |
| </blockquote><!-- mutations -->
| |
| | |
| | |
| </blockquote><!-- basics -->
| |
| | |
| = Syntax =
| |
| <blockquote>
| |
| == Objects ==
| |
| <blockquote>
| |
| | |
| {{ expand
| |
| | Fields with Arguments
| |
| |
| |
| <source lang="ruby">
| |
| class User < GraphQL::Schema::Object
| |
| field :id, Integer # name, returntype
| |
| field :age, Integer # name, returntype
| |
| end
| |
| | |
| class MyGraph < GraphQL::Schema::Object
| |
| field :user, User, do |field|
| |
| field.argument(:id, Integer, required: true)
| |
| end
| |
| end
| |
| </source>
| |
| }}
| |
| </blockquote><!-- objects -->
| |
| | |
| == Mutations ==
| |
| <blockquote>
| |
| Mutations are graphql fields that trigger side effects.
| |
| | |
| * mutations return a hash, that contains all of the fields defined on it.
| |
| * mutations may optionally accept arguments
| |
| | |
| <source lang="ruby">
| |
| class MyMutation < GraphQL::Schema::RelayClassicMutation
| |
| argument :username, String, required: true
| |
| | |
| field :message, String, null: true # returns string, allows null
| |
| field :errors, [String], null, false # returns list of strings, disallows null
| |
| | |
| def resolve(username)
| |
| # do thing that produces side effect
| |
| { message: "Hello #{username}",
| |
| errors: [] }
| |
| end
| |
| end
| |
| | |
| | |
| class MyMutationRoot < GraphQL::Schema::RelayClassicMutation
| |
| field :mymutation,
| |
| mutation: MyMutation # TODO: needs arg??
| |
| end
| |
| | |
| | |
| class MyGraph < GraphQL::Schema
| |
| mutation(MyMutationRoot)
| |
| end
| |
| </source>
| |
| </blockquote><!-- Mutations -->
| |
| | |
| == Connections ==
| |
| <blockquote>
| |
| Connections between nodes are expressed as edges.<br>
| |
| Edges can be abstracted as connections to support query params, filters, pagination, etc.<br>
| |
| | |
| See https://graphql-ruby.org/relay/connections.html
| |
| | |
| <source lang="ruby">
| |
| # Defines a `ClassType`, with the connection `StudentType`.
| |
| | |
| class ClassType < GraphQL::Schema::Object
| |
| field :students, StudentConnectionType,
| |
| connection: true,
| |
| description: "Students that belong to a class"
| |
| end
| |
| | |
| class StudentConnectionType < GraphQL::Types::Relay::BaseConnection
| |
| edge_type StudentEdgeType
| |
| end
| |
| | |
| class StudentEdgeType < GraphQL::Types::Relay::BaseEdge
| |
| node_type StudentType
| |
| end
| |
| | |
| class StudentType < GraphQL::Schema::Object
| |
| field :id, Integer
| |
| field :age, Integer
| |
| field :username, String
| |
| end
| |
| </source>
| |
| </blockquote><!-- Connections -->
| |
| </blockquote><!-- syntax -->
| |