graphql.tar.gz

graphqlspa

graphqlcodewidget

In this course, you will learn what exactly GraphQL is, how to design a robust and scalable API with it, and how to implement it in NodeJS.

You’ll start by running through the pros and cons of GraphQL in order to get a feel for its limitations and what its applications are. You’ll then take a brief look into the REST vs GraphQL debate and understand the reasons for and against both.

In the latter half of the course, you’ll explore things like GraphQL types, schemas, and mutations. In the last few sections, you’ll take what you’ve learned and make a GraphQL API in Node while scaling it for consistency.

Up and running with Node and GraphQL

# Introduction

Now that you understand the basic pieces that make up a GraphQL schema, it is time to learn how to assemble them into something meaningful.

A good API design is not reliant on using a specific technology. Rather, it is reliant on how you want your end-user to interact with your service.


With that said, GraphQL _does_ make it easier, in some respects, to create an intuitive and performant API.

# What to aim for

A good API is one that makes it clear what you are doing and how you will do it. That is to say, that at any point in its use, you should be certain what the result will be and how to arrive at that point.

You do not want to create an API that frustrates your users with side effects or leaves the uncertainty on how they are meant to retrieve or manipulate data.

For the most part, the key to this is not how clever your code is. The key is how you express your API.


# Naming

>There are only two hard things in Computer Science: cache invalidation and naming things.

-- Phil Karlton

People make sense of their environment through labeling. We collate our knowledge by assigning it some kind of label.

An API is no different, and what often makes an API intuitive is how it names its operations.

One of the easiest wins when it comes to good API naming is to be consistent in your naming patterns. Take the following example:


```graphql
Query {
   getUsers: [Users]
   listPhotos: [Photos]
}
```

Although both make sense on an individual level, you end up with the scenario where developers are asking themselves:

>What was it again? `getThis` or `listThat`?

At best, you end up with an error during development or need to check the schema, and at worst, you end up with a bug in production. Either way, it can be a frustrating experience.

Language is important, and API design is no exception to this. Keep your naming consistent, and users will thank you.

## Be specific

Additionally, it is important to be specific when naming types, fields, and other names. There are several reasons why:

First, it provides additional context to an Object Type or field. Consider this example:

```graphql
type Photo {
   id: ID!
   url: String!
} 
```

When you first write your schema, this seems fine. But as your codebase grows and features are added, you may run into trouble. 

Let’s say your manager decides that we are adding a gallery section to the website. No problem! However, the `Photo` Object Type was previously storing user avatars. Should we store gallery photos in there as well now?

So, now you end up with something like this:

```graphql
type Photo {
   id: ID!
   url: String!
}

type GalleryPhoto {
   id: ID!
   url: String!
   galleryCaption: String
}
```

This *works*, but it feels clumsy. Now we are left with a generic  `Photo` type, which, in reality, is for users, and a specific `GalleryPhoto` type.

If we had thought ahead with our schema design, we would have created the schema like this:

```graphql
type UserProfilePhoto {
   id: ID!
   url: String!
}
```

This is explicit, easy to reason with, and does not stop us from adding similar types down the line. It also saves us from doing frustrating depreciations of our types to write the schema in the way it should have been done to begin with.

In short, try not to share types too much. When you do, think about the potential side-effects.


Learn how to effectively structure a GraphQL schema and create an API that developers will love to use.

__default

How GraphQL Schema Works

Introduction