Prisma1: [Prisma 1.0] Specifications

[nikolasburk]

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.

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

[mlukaszczyk]

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!

[nikolasburk]

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?

[sorenbs]

@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 https://github.com/graphcool/graphql-remote

@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 :-)

[nikolasburk]

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.

[mlukaszczyk]

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

[sorenbs]

@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 :-)

[maxdarque]

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 🥇 💯 👍

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed in 10 days if no further activity occurs. Thank you for your contributions.