GraphQL vs REST

REST is an architectural approach to creating web services. GraphQL is a query language for designing APIs. Both are used to create web services allowing clients to communicate with remote servers over HTTP.

While REST has been widely accepted as the “de facto” for developing stateless independent microservices, GraphQL is the new kid on the block for rapid API development.

What is REST?

REST stands for Representational State Transfer. REST isn’t a library but rather an architectural “way of doing things”. Web services are considered RESTful when their implementation adheres to REST principles.

A core concept behind REST is the idea of resources. A resource represents a piece of data you want to retrieve from the server. If your web app is a blog then resources may include posts, comments, users, etc.

Each resource is identified by a URL. You fetch a given resource by sending a HTTP request that may look something like this:

/users/<id>/posts

The server processes your request and returns something like this:

{
  "posts": [
    {
      "title":"My latest post",
      "author":"Sam",
      "views":33
    },
    {
      "title":"My other post",
      "author":"Sam",
      "views":14
    },
    {
      "title":"My first post",
      "author":"Sam",
      "views":53
    }
  ]
}

For a user with a given , the service returns a JSON object with an array of post objects.

What is GraphQL?

Unlike REST, GraphQL is an actual application query language for making HTTP requests that return specified resources. While GraphQL ultimately uses the same HTTP protocol to retrieve information from the server, it leverages a type system defined in a schema. This schema dictates the types of queries that can be run and the data they return.

Unlike REST, GraphQL produces a single API endpoint for communicating with the server.

Let’s see how GraphQL would implement the same REST call from the previous example:

query {
  User(id: <id>) {
    posts {
      title,
      author,
      views
    }
  }
}

The server processes the request and returns:

{
  "posts": [
    {
      "title":"My latest post",
      "author":"Sam",
      "views":33
    },
    {
      "title":"My other post",
      "author":"Sam",
      "views":14
    },
    {
      "title":"My first post",
      "author":"Sam",
      "views":53
    }
  ]
}

Notice how the exact same JSON response is returned using GraphQL…

So whats the point?

From the examples, it looks like both GraphQL and REST produce the same result. The GraphQL query seems a bit more verbose than a simple GET request, but both ultimately use the same protocol to return the same thing. So what’s the big deal?

Overfetching and underfetching data

One of the main reasons why GraphQL is preferred to REST is the precision with which data is retrieved from the server. While our basic /users//posts endpoint gave us the data we needed, it may have given us more than we asked for. For example, what if we only wanted the title returned for each post?

This is known as “overfetching” since we got back more than we asked for. Specifically, we got back the author and views along with the title.

Another scenario could be that you need more information about each post. In addition to views, authors, and titles you may also want the number of likes for a given post, etc. This is considered “underfetching” and results in additional requests needed for each post object being returned.

You may be thinking…so what? After all, you could modify the REST endpoint to accept parameters for each field you want returned. You could even filter at the database level or create a new endpoint all together.

And you aren’t wrong. But this would require more development work and more coordination across different teams.

Alternatively, with GraphQL we could simply modify our original query to address the “overfetching” problem:

query {
  User(id: <id>) {
    posts {
      title
    }
  }
}

or the “underfetching” problem:

query {
  User(id: <id>) {
    posts {
      title,
      author,
      views,
      followers
    }
  }
}

Notice how in both cases we simply add or subtract fields that we want returned. Remember GraphQL uses the same API endpoint for every query…so no need to bug the API team.

One request to rule them all…

This example clearly illustrates the benefits of using GraphQL over REST. By specifying a clearly designed schema with the data types and queries available, GraphQL implements a more contract-driven approach to communicating with the server.

This better isolates the front end from the back end and allows for more rapid API development as quickly evolving UIs can retrieve the exact information they need.

GraphQL vs REST: Pros and Cons

So should you forget about REST completely? Not at all. It’s important to remember that REST remains one of the most popular approaches to microservice architecture. Deciding between GraphQL vs REST depends on how you emphasize the pros and cons of each.

REST pros:

• widely accepted- REST has been around since 2000 and remains one of the most popular approaches to implementing web services today.
• reusable - using REST, you can more easily develop independent microservices that work independently of one another. Microservices are (ideally) fully decoupled from clients allowing for them to be accessed by multiple applications.
• caching - REST inherently supports caching much better than GraphQL. This makes for better performance out of the box.

REST cons

• excessive round trips - more endpoints requires more requests. We saw how the problem of underfetching can lead to excessive requests over the network.
• versioning - to avoid breaking changes, REST APIs must implement versioning to ensure production services continue working even when updates are made. This can get messy as more and more versions of your API are released.
• overfetching - downloading unnecessary data
• underfetching - not retrieving enough data, resulting in additional requests
• coordination efforts - it’s more difficult to develop front ends independently of back ends since new requirements require new endpoints (or modification of existing endpoints).

GraphQL pros

• schema - by defining a schema with types of data and queries, GraphQL creates a contract between the client and the server making the data available to the client more obvious. Front end developers don’t need to concern themselves with back end.
• easy to get started - you don’t have to be an expert with web service architecture to start producing / consuming GraphQL.
• precision - you can retrieve exactly the data you’re looking for without additional endpoints or modification of those endpoints. GraphQL more efficiently addresses the overfetching/underfetching problem.

GraphQL cons

• scalability issues - GraphQL is easy to get started with, but can become more of a performance issue as complex queries surface and grow.
• schema limitations - With GraphQL, you’re stuck with the schema that’s defined. This can cause headaches when you want more in-depth responses than provided.
• still fairly new - GraphQL is still considered the new kid on the block. There are only a few select clients that implement it well (Apollo, Relay, and Lokka among the most popular GraphQL clients).

Conclusion

While arguing the pros and cons of GraphQL vs REST can be a never ending conversation, it’s important to remember that both achieve the same end result. Both invovle sending HTTP requests and receiving data from a server. Both have the idea of resources and can specify IDs for those resources. Both can return JSON responses.

Answering the question as to which is better for your web service really depends on the dynamic between different dev teams in your organization. If you already follow a microservice architecture, then dropping REST to play with GraphQL may not be the best idea. However if your team emphasizes rapid API development driven by the front end, then GraphQL may be the best fit for you.

Originally published at https://www.stackchief.com

#rest #graphql #database

What is GEEK

Buddha Community

What is REST API? An Overview | Liquid Web

What is REST?

The REST acronym is defined as a “REpresentational State Transfer” and is designed to take advantage of existing HTTP protocols when used for Web APIs. It is very flexible in that it is not tied to resources or methods and has the ability to handle different calls and data formats. Because REST API is not constrained to an XML format like SOAP, it can return multiple other formats depending on what is needed. If a service adheres to this style, it is considered a “RESTful” application. REST allows components to access and manage functions within another application.

REST was initially defined in a dissertation by Roy Fielding’s twenty years ago. He proposed these standards as an alternative to SOAP (The Simple Object Access Protocol is a simple standard for accessing objects and exchanging structured messages within a distributed computing environment). REST (or RESTful) defines the general rules used to regulate the interactions between web apps utilizing the HTTP protocol for CRUD (create, retrieve, update, delete) operations.

What is an API?

An API (or Application Programming Interface) provides a method of interaction between two systems.

What is a RESTful API?

A RESTful API (or application program interface) uses HTTP requests to GET, PUT, POST, and DELETE data following the REST standards. This allows two pieces of software to communicate with each other. In essence, REST API is a set of remote calls using standard methods to return data in a specific format.

The systems that interact in this manner can be very different. Each app may use a unique programming language, operating system, database, etc. So, how do we create a system that can easily communicate and understand other apps?? This is where the Rest API is used as an interaction system.

When using a RESTful API, we should determine in advance what resources we want to expose to the outside world. Typically, the RESTful API service is implemented, keeping the following ideas in mind:

• Format: There should be no restrictions on the data exchange format
• Implementation: REST is based entirely on HTTP
• Service Definition: Because REST is very flexible, API can be modified to ensure the application understands the request/response format.
• The RESTful API focuses on resources and how efficiently you perform operations with it using HTTP.

The features of the REST API design style state:

• Each entity must have a unique identifier.
• Standard methods should be used to read and modify data.
• It should provide support for different types of resources.
• The interactions should be stateless.

For REST to fit this model, we must adhere to the following rules:

• Client-Server Architecture: The interface is separate from the server-side data repository. This affords flexibility and the development of components independently of each other.
• Detachment: The client connections are not stored on the server between requests.
• Cacheability: It must be explicitly stated whether the client can store responses.
• Multi-level: The API should work whether it interacts directly with a server or through an additional layer, like a load balancer.

#tutorials #api #application #application programming interface #crud #http #json #programming #protocols #representational state transfer #rest #rest api #rest api graphql #rest api json #rest api xml #restful #soap #xml #yaml

Graphql vs Rest: “What the Fudge” Issues I Faced Consuming a 50+ Endpoint Rest API

We see a lot of articles that tout the features of graphql, praising its advantages over rest API’s, I do mostly agree with these articles, but I’ll like to present its advantages from another perspective — by elaborating some issues I had integrating a 50+ rest api in an app.

Issue #1 What You See is Not Always What You Get.

API Documentation isn’t documentation when it doesn’t accurately represent the complete range of input-output relationships.

The api docs whilst mostly accurate, left me guessing at which data types were accepted and the range of values fields could take.

Using a standard rest API felt like I had to have “faith” on the documentation in exactly what had to be returned, and frustration ensued when it didn’t correlate with expectations.

#rest-api #graphql #graphql-vs-rest #api

Interacting with APIs: REST and GraphQL

You should be open to using the best tools for the job, which may include both GraphQL and REST.
Treat the graph as a data-driven hierarchy defined by plural nouns: A well-formed GraphQL should look like a well-formed REST.

Don’t force GraphQL when REST makes more sense
In REST, users often request and submit data from different URLs, especially when using patterns such as Command Query Responsibility Segregation (CQRS), a design pattern first identified by Martin Fowler that separates the model that reads the data from the model that updates the data.

In GraphQL, mutations (the way a GraphQL developer submits data) can get very complex very quickly, especially when there are a lot of different data types or when very little data is submitted.

Optimize for re-usability 
In GraphQL, it’s easy to optimize for query efficiency, but be intentional about optimizing for re-usability. Avoiding situations in which APIs confuse developers will pay dividends.

#graphql #rest #apis #rest and graphql

RESTful APIs Are Good, But GraphQL APIs Are Usually Better

GraphQL APIs draw a natural comparison and contrast to RESTful APIs. I should mention in the very beginning there are benefits to both approaches. Don’t force adopt GraphQL when REST makes more sense. Even if you do decide to go with GraphQL APIs, be sure to continue REST-based best practices. For example, optimize for reusability.

A core distinction of GraphQL is it is optimized for performance and flexibility. A big part of this is instead of returning a complete dataset, GraphQL allows you to tailor the request to just give you the data you need. This is a notable change from RESTful APIs since REST endpoints don’t allow you to tailor the data that is returned. Another advantage is operations that would require multiple RESTful API calls can be simplified to a single GraphQL API call.

#graphql #restful #apis #graphql apis #restful apis

GraphQL vs REST: putting REST to rest

When you need to build an API, your mind will likely jump to REST, the de facto standard for API creation. However, this is about to change with GraphQL, as its popularity quickly rises.

Not everyone fully understands yet what GraphQL is all about, or why it’s being declared as the successor of REST, and that’s exactly what I’ll clear up in this article. Here I’ll show off GraphQL’s main features and the advantages that it has over REST, highlighting a few points in which both differ.

The goal is to provide a brief explanation to anyone who still hasn’t got to know GraphQL, and clarify exactly what it does better than REST, for those who are still skeptic about this technology.

Let’s start with the very basics.

What is GraphQL?

GraphQL is a query language for APIs that enables declarative data fetching in order to give the client the power to specify exactly the data that is needed from the API.

A question that I see asked a lot is:

Why was GraphQL created when we already have REST?
There are two main reasons why companies such as Facebook, Netflix and Coursera started developing alternatives to REST:

1. In the early 2010s there was a boom in mobile usage, which led to some issues with low-powered devices and sloppy networks. REST isn’t optimal to deal with those problems;

2. As mobile usage increased, so did the number of different front-end frameworks and platforms that run client applications. Given REST’s inflexibility, it was harder to develop a single API that could fit the requirements of every client.

If we go even further, we realize that the main reason why an alternative solution was identified was because most of the data used in modern web and mobile applications has a graph shape. For instance, newspieces have comments, and those comments may have features such as likes or spam flags, which are created or reported by users. This example describes how a graph looks like.

Consequently, Facebook started developing GraphQL. At the same time, Netflix and Coursera were also working on alternatives themselves. After Facebook open-sourced GraphQL, Coursera dropped their efforts and adopted the new tech. Netflix, however, continued developing their own REST alternative and later open sourced Falcor.

What GraphQL isn’t

Now that we know what GraphQL is, I want to clarify what it is not, as I feel that there’s still some confusion about it.

Firstly, it doesn’t have anything to do with databases. It isn’t an alternative to SQL or a brand new ORM.

Secondly, it isn’t a REST replacement, but an alternative. You don’t have to pick between one and the other, they can happily co-exist in the same project.

Last but not least, GraphQL isn’t complicated or scary. It’s quite easy to understand its declarative nature and exactly how it’s possible to take the best from it.

GraphQL in context

Before moving on to the comparison with REST, I’ll go through a simple GraphQL query where we can fetch a user as well as his or her name and age:

query {
  user {
    name
    age
  }
}

And the JSON response we’ll get from it:

{
  "user": {
    "name": "Johnathan Joestar",
    "age": 27
   }
}

As I stated previously, GraphQL’s declarative nature makes it incredibly easy to understand what’s going on at all times, as we are basically writing JSON objects without the values.

Now that we have context, let’s dive deep into GraphQL’s features and the advantages that it has over REST.

GraphQL vs REST

In this section I’ll go point by point through a practical example, comparing REST to GraphQL in order to demonstrate the flexibility of Facebook’s query language.

Imagine that you have a blog, and you want the front page to show all the latest posts. In order to achieve this, you need to fetch the posts, so you will probably do something like this:

GET /api/posts

[
  {
    "title": "Cooler post",
    "subtitle": "...",
    "date": "07/05/2019"
  },
  {
    "title": "Cool post",
    "subtitle": "...",
    "date": "06/05/2019"
  }
]

But what if you want to see the author as well? You have three options to achieve this:

• Fetch the authors from another resource:

GET /api/post/:id

{
  "post": {
    ...,
    "author": {
      "name": "Dio Brando"
    }
  }
}

• Modify the resource to also return the author:

GET /api/posts

[
  {
    ...,
    "author": {
      "name": "Dio Brando"
    }
  },
  {
    ...,
    "author": {
      "name": "Johnathan Joestar"
    }
  }
]

• Create a new resource that returns the posts with the author:

GET /api/postsWithAuthor

[
  {
    ...,
    "author": {
      "name": "Dio Brando"
    }
  },
  {
    ...,
    "author": {
      "name": "Johnathan Joestar"
    }
  }
]

Each of these approaches will create a problem of its own, so let’s have a look at them one by one.

Under-fetching

With the first approach – fetching the authors from another resource – you’ll end up with two server requests instead of one, and as you continue to scale, you may have even more requests to different endpoints in order to fetch all the needed data.

With GraphQL, this wouldn’t happen. You would only have one request, and you wouldn’t have to make multiple round trips to the server, as seen below:

query {
  posts {
    title
    subtitle
    date
    author {
      name
    }
  }
}

Over-fetching

Looking at the second approach – modifying the resource to also return the author – you can see that it solved the problem pretty nicely. However, changing a resource may have a secondary effect elsewhere on your application. More precisely, over-fetching.

Let’s go back to your blog, but this time you also have a sidebar showing off the top monthly posts with their titles, subtitles and date, that is using the resource /api/posts. Since you modified the resource, now it also shows the author with it. However, we don’t need it for the sidebar.

While this may not look like a problem, for users on limited data plans, having a website fetch useless data isn’t ideal. Since GraphQL allows the client to only fetch the needed data, this problem wouldn’t exist:

query {
  posts {
    title
    subtitle
    date
  }
}

Slow front-end development

Lastly, let’s have a look at the last approach – creating a new resource that returns the posts with the author – since it’s a common pattern to structure the endpoints according to the views in your project.

While this may solve problems such as the one described above, it also slows down the front-end development, since each specific view needs its specific endpoint. If at any point a view needs new data, the development has to slow down until the endpoint is updated.

Again, since GraphQL gives power to the client to fetch the needed data only, nothing slows down, as it’s very simple to just add a new field to a query.

You would get from this:

query {
  posts {
    title
    subtitle
    date
  }
}

To this:

query {
  posts {
    title
    subtitle
    date
    author {
      name
    }
  }
}

REST vs GraphQL comparison recap

Let’s just do a quick recap regarding the differences between REST and GraphQL:

• GraphQL solves both over-fetching and under-fetching issues by allowing the client to request only the needed data;
• Since the client now has more freedom in the fetched data, development is much faster with GraphQL than what it would be with REST.

Now we’ll move on to a more in-depth overview of GraphQL’s unique features.

GraphQL’s features overview

Now that we know how it stacks up against REST, let’s talk about some of the features that are unique to GraphQL.

Schema and Type System

GraphQL uses its own type system to define the schema of an API, with its syntax called Schema Definition Language (SDL). The schema serves as a contract between the server and the client to define how a client can access the data.

Once the schema is defined, the front-end and back-end teams can work independently, as the front-end can be easily tested with mock data. The front-end can also get useful information from the schema, such as its types, queries and mutations using GraphiQL or introspection. The schema also provides type safety, which is a plus for the front-end and back-end development, as it catches type errors early.

A schema example:

type User {
  name: String!
  age: Int
  posts: [Post!]!
}

type Post {
  title: String!
  subtitle: String!
  body: String!
  date: String!
  author: User!
}

type Query {
  users: [User!]!
  user(name: String!): User!
  posts: [Post!]!
  post(title: String!): Post!
}

type Mutation {
  createUser(name: String!, age: Int): User!
  createPost(title: String!, subtitle: String!, body: String!): Post!
}

GraphQL IDE

This is one of the most useful features of GraphQL development. A GraphQL IDE takes advantage of its self-documenting nature to make development a breeze.

Using GraphiQL or GraphQL Playground, you can just inspect your schema and even run queries and mutations to test out your API.

GraphQL Playground

Wrap up

GraphQL provides a smooth and fast development environment with its declarative and flexible nature, offering many improvements over REST. Despite being relatively new, it has already been adopted by companies such as Facebook, GitHub and many more .

It already has a large community and a vibrant ecosystem, and was already implemented in several popular languages, such as JavaScript, Go and Java.

While this post only dipped the toes into the ocean that is GraphQL, its website has a plethora of information and is an amazing place to learn and start using GraphQL.

With all this being said, it’s not a perfect technology, and it still has a couple of drawbacks when compared with REST. But considering how young it is, the future looks incredibly bright for GraphQL.

#graphql #rest