An introduction to Graphcool framework Graphcool is a framework for production-ready serverless GraphQL backend and launch. It in October 2017. Graphcool includes GraphQL database mapping, real-time subscriptions, and a flexible permission system. development became open-source GraphQL and Graphcool background Graphcool is based on GraphQL, so let’s discuss it a little. GraphQL is a query language specification, that was launched in 2015 by Facebook. GraphQL provides more flexible possibilities of backend communication than REST. With REST, you get many endpoints to work with resources, but GraphQL has a single endpoint, while your needs are described in the query itself. The name of GraphQL communicates that it represents the data in a graph form. (The main ideal of GraphQL, actually enclosed in its name, is to represent data in a graph form) Here is a example. Let’s say you want to retrieve a message with all its comments and its author’s information. Facebook Using REST API, you need to send several queries to get the message, its comments, and the author’s data. With GraphQL API you can retrieve this data with a single backend reply since you determine which data you need in return to your query. Learn more about GraphQL . here For the client to understand which data he or she can query from GraphQL backend, the scheme written on GraphQL Schema Definition Language is used. The scheme is a data model, it describes the data types in your application and their relations. GraphQL Schema Definition is the shortest way to present the scheme of GraphQL. The syntax is defined by the official GraphQL specification. Scheme definitions are sometimes called IDL (Interface Definition Language) or SDL (Schema Definition Language). GraphQL scheme for application in a blog can be represented this way. GraphQL is only a specification, so in order to use it, you will need a service for the specification implementation. You can create your own service or use GraphQL Backend-as-a-Service (BaaS), like Graphcool. Graphcool takes care of saving your data and provides a GraphQL endpoint for your application. All you need to do is to determine the Graphcool scheme, and it will automatically generate functions for data query and editing. If your application requires real-time updates, you can use GraphQL subscriptions. Graphcool also offers data storage, third-party authentication integration and server functions for business logic, so it is a truly versatile solution for applications. Graphcool usage There are two development methods based on Graphcool: local and cloud-based. Graphcool Cloud has been online for 2 years now and provides several possibilities for project launch. Shared Cluster uses pay-as-you-go model and allows automatic scaling according to your requirements. Private Cluster is similar to Shared Cluster but is based on your own infrastructure and the AWS account. Thanks to Graphcool Framework, Graphcool can be launched on a personal computer. As a result, the development process is accelerated, including both autonomous development and CI pipeline integration. Today we’ll cover local development. Graphcool APIs Graphcool provides automatically generated CRUD API for your data model. It also offers real-time API, using GraphQL subscriptions and a dedicated API for file management. Graphcool’s main advantage is the automatic generation of CRUD API based on the data model you choose for your service. This API provides features for filtration, sorting, and paging. Every Graphcool service is provided with real-time API based on GraphQL subscriptions, and it allows for timely reaction to the system events. Remember that every Graphcool service by default is provided with two different API interfaces: Simple API is responsible for intuitive CRUD operations and data modeling. Relay API meets the requirements of the Relay scheme. Both APIs turn to the same database! Graphcool query structure That’s how a query for all entries of the same type and its response look like. The query consists of the query name (in this case — all) and a list of fields you wish to retrieve. The response comes back as an array of objects with their keys being the fields specified in the query. This way you can get a certain entry by node ID. Specify the model type, with the needed node ID in brackets and list the fields. The response will contain the object of the necessary type. You can also get a certain node by a unique field. Instead of the node’s ID, we conduct a search by the unique field. These are the arguments for data organization: Field sorting. orderBy: <field>_ASC/<field>_DESC. Specify the field and the sorting order. Filed filtration. Paging. These arguments can be combined. At the moment, there are some limitations for these arguments’ usage: There is no way to request a response by several fields or by related fields. The maximum number of the return data objects is 1000. Graphcool Filtration Filtration deserves extra attention. Graphcool can filtrate data by the required node itself as well as by the related nodes. Logical operators AND/OR broaden the filtration possibilities. Graphcool can use in/lt/lte/gt/gte/contains/starts with/ends with operators and their negation. For every field type, there are certain filters, and text type example allows you to see most of them. Of course, there are limitations. Array and JSON filtration haven’t been realized yet. Creating, Updating And Deleting A Node Every new node created for a specific type gets assigned a new ID. All required fields without default values have to be specified, the other fields are optional arguments. The query response can contain all fields of the newly created node, including the ID field. Updating a node is performed similarly, but the query data should include the node ID. Nested mutations are possible for creating and updating a node. As a result, one query allows you to create or update all related nodes. At the moment the maximum nesting level is 3. If you require a higher nesting level, you will need to create a new query. To delete a node, you need to specify the node ID. Unfortunately, nested and cascade delete is not supported at the moment. Graphcool Templates Graphcool supports a template system to accelerate development. New templates added through the console can be instantly used by the client. Templates mostly do not require any changes, however, any necessary adjustments can be easily made to accommodate your scheme. Templates’ source code is added to your work directory. Currently, a list of official templates isn’t long, here are some of them: Authentication templates for email-password, Google, Facebook, Auth0 Messaging templates: mailgun, ses, push (push notifications) or twilio (SMS). There are also unofficial templates. Graphcool Authentication Token-based templates are used for authentication in Graphcool. The use of rootToken is enabled for your application. Using authorization system, permission rules can be easily created and integrated with authentication. Graphcool provides a very flexible function-based authentication system. With Graphcool, you can identify the API operations requiring authentication. An HTTP-query, that performs an operation, should possess a valid authentication token in its authorization header. Otherwise, the query will be aborted due to an invalid permission. Graphcool Permissions Permissions are described in graphcool.yml. Within a permissions block, you can list what types of permissions are required. Restrictions can be placed on operations and the relations between operations. To place a restriction, you need to define which operation is limited to a certain node. Next, identify the user type the operation is available for (authorized or not). You can select certain node fields for which the restriction will apply and identify specific restriction rules. Permissions are based on the filtration system. Just specify necessary values for every field. With Graphcool, such query will get you user_id of the current user and the data of the current account that is being checked. Graphcool’s pros and cons Let’s sum up Graphcool’s advantages and disadvantages. Obviously, there are some drawbacks: MySQL schema generated by Graphcool is quite specific. There are no relations between the tables. The relations are contained within the tables with related nodes’ IDs. Upon MySQL container initialization, Graphcool creates a database for metadata (project ID and primary data, user features, relations, webhooks, some user data). Upon application deploy, a separate database is created and is named using a generated ID. It contains tables, specified in graphcool.yml. Aside from tables containing the described nodes, there are tables for node relations. Cascade delete is not possible due to a lack of relations. The project is fairly new to open-source, and documentation leaves a lot to be desired. There are no plugins for syntax support in IDE. The only saving grace is the Intellij IDEA plugin that has GraphQL support. Now it’s time for the advantages: Development speed is extremely high. Just define the scheme, and Graphcool will do the rest. Graphcool can utilize resolvers written using JavaScript and TypeScript, thus broadening its potential. There is a strong filtration feature that allows you to get necessary return data with little effort. Graphcool can work with files in the cloud storage. Templates increase development speed and provide tried solutions. The learning curve is low. Learn how to create a scheme using GraphQL, and you can start working. Seeing as Graphcool is based on GraphQL, they share most advantages and disadvantages. In certain aspects, Graphcool is getting better, but there is still a long way to go. Project utilization In the course of our research, it was decided to implement the framework in a real project using PostgraphQL to compare these technologies. The project’s primary nodes and CRUD operations were created, authorization and advanced sharing system (infrastructure objects sharing according to user roles and groups) were implemented. It took 3 days to develop backend. As Graphcool possesses out-of-box nested mutations and flexible filtration system, there was no need to create custom resolvers, and everything was implemented using only framework’s features. Graphcool vs Postgraphql Custom endpoints. Graphcool has almost no limitations, which allows for JS usage. PostgraphQL is limited by the database. CreateOrUpdate. There is Upsert in Postgres, but you can’t use it in PostgraphQL. In Graphcool it is out-of-box. Nested mutation. PostgraphQL doesn’t create or update related nodes, it can only be done by separate queries. Raw SQL query. Currently, Graphcool cannot map the database scheme for the GraphQL scheme. Filtration. Graphcool provides a wide array of settings, can compare rows, dates, arrays, while PostgraphQL can only compare keys or values. Automatization. Graphcool possesses automated triggers for createdAt/updatedAt fields, relation operations. The same operations need to be performed by hand in PostgraphQL. Calculated fields. Graphcool does not support calculated fields as of now. They are only supported through separate resolvers. Cascade delete. Graphcool doesn’t support cascade delete due to the specifics of the database. Data aggregation. Graphcool does not work with internal database functions that could aggregate data according to your needs. Conclusion As you see, Graphcool is an interesting and powerful framework. However, since it has become open-source only recently, it still has some problems that are being solved through the cooperation of developers and users. The work continues to ensure other databases support, data aggregation and cascade delete. As a developer, I think Graphcool is best suited for small and middle-sized projects and for rapid prototyping, as it offers many features out-of-box (nested mutations, flexible filtration system, templates, custom mutation written on JS/TS) and does not require in-depth SQL knowledge. Final words I need to mention that I am a co-author on this article. Link to the original article can be found here . https://freshcodeit.com/blog/2017/12/26/graphcool-framework-analysis-and-practical-cases/ Make sure to take a look at FreshCode IT company website at this link , a lot of great articles can be found on their blog. https://freshcodeit.com/ Thanks for reading.
