New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Prisma 1.0] Specifications #353

nikolasburk opened this Issue Aug 24, 2017 · 7 comments


None yet
6 participants

nikolasburk commented Aug 24, 2017

Over the last two years we have learned a lot about how best to design a GraphQL API. This document collects our learnings and is the first step toward a new better API. At the current state this is very much WIP.

API and Feature Specifications

Unchecked items are not yet finalized or have open questions.

  • Improved service deployment reliability #595
  • Query API #1340
  • Data Import #1299
  • Generated type names #1341
  • Database seeding #1181
  • Reference by any unique field #1267
  • More powerful scalar lists #1275
  • Embedded Types #1160
  • Cascading Deletes #1262
  • updateMany & deleteMany #81
  • Bring your own id, createdAt, updatedAt #1278
  • Index support #1300
  • Interfaces and Polymorphic relations #83
  • Filter on aggregated values #1279
  • Improved API for nested mutations #1280
  • Aggregations #1312
  • Migration based deployment #1263
  • New graphcool.yml format #1328
  • New CLI commands layout #1330
  • Deployment targets should be service name instead of generated service ID #1329
  • Change db structure for enums
  • Atomic Operations #1349
  • Request logs #749
  • Cluster configuration cluster.yml #748
  • Platform Authentication #1365
  • Direct database access #1375
  • Cluster Version #1376
  • Changes to SDL #1380
  • Non-null fields #1382
  • Rename service and stage #1414
  • Delete service #1415
  • Endpoints #1417

API Flavours

In the past we supported two different APIs. One that is relay compliant and one that is simpler to use. In practice it has turned out that 80% of all queries against Graphcool use the simple API.

For our new API we want to maintain the simplicity of the simple API while adopting a few best practices from relay that doesn't clutter the API unnecessarily:

  • wrap input fields in a data argument for better tooling support
  • have both a relation and relationConnection field

The relationConnection field is relay compatible and provides a place to add extra relation-related functionality such as aggregations.

The GraphQL Gateway provides an easy way to exclude fields you don't want to expose in the final API

The API is describe in detail in #1340


This comment has been minimized.

mlukaszczyk commented Nov 24, 2017

Some query API feedback:
I really like the style of alternative 2 (looks cleaner to me) but I guess alternative 1 will make the transition a lot easier as it is not introducing breaking changes. Is there already a preference on your side?

Really looking forward to all of this!


This comment has been minimized.


nikolasburk commented Nov 25, 2017

Just a quick question about the new API to query a single node which currently capitalizes the field on Query, e.g.:

type User @model {
  id: ID! @isUnique

Which leads to a Query:

type Query {
  User(id: ID!): User
  # ... more

Is it the plan to still capitalize this field?


This comment has been minimized.


sorenbs commented Nov 25, 2017

@mlukaszczyk Currently we are leaning towards alternative 1 as it is a less dramatic change, is directly compatible with relay and plays nicer with the delegate pattern of

@nikolasburk great question. Current plan is to stay with uppercased single node fields. If there are good arguments against, I would like to hear it :-)


This comment has been minimized.


nikolasburk commented Nov 25, 2017

My main point against capitalizing it is just consistency (and convention). Might only be me, but I haven't come across any GraphQL schemas in the past that capitalized fields. And I've seen people being thrown off by the capitalization in our API. Not sure how strong this argument weighs, but to me it would be more consistent to lowercase all fields.


This comment has been minimized.

mlukaszczyk commented Nov 28, 2017

@sorenbs fully on board with that! Please share some news as soon as the decision is made.


This comment has been minimized.


sorenbs commented Dec 1, 2017

@mlukaszczyk We are going for option 1 and incorporate the change suggested by @nikolasburk to lowercase all fields. See #1340 for the details

We will have the first super-early beta of this API ready in about a week for you to try out :-)

@sorenbs sorenbs referenced this issue Dec 4, 2017


Authentication #1365

0 of 1 task complete

@schickling schickling changed the title from Graphcool 1.0 to [Graphcool 1.0] Specifications Dec 13, 2017


This comment has been minimized.

maxdarque commented Dec 14, 2017

The Graphcool project is amazing 👍 the speed at which you can built a CRUD interface and incorporate serverless functions with ease is astonishing. As a first time web dev, I've been able to build a comprehensive web app using react + apollo client + graphcool (w/ TS functions). So thank you. Big fan :)

It would be great to have File Permissions. See Issue #143

I don't have much experience as a developer. I'm heavily reliant on graphcool to do everything in my backend. Files at the moment are not secure so I can't launch a full production app until I implement a solution. With File Permissions, graphcool can be that one-stop-shop for your backend 🥇 💯 👍

@marktani marktani changed the title from [Graphcool 1.0] Specifications to [Prisma 1.0] Specifications Jan 22, 2018

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment