Sofa — The best way to REST (is GraphQL)

Ending the REST vs GraphQL debate once and for all

Urigo
Urigo
Jan 25, 2019 · 7 min read
Activate REST API in a snap

TL;DR

  • Don’t choose between REST and GraphQL — create a fully RESTful API automatically from your GraphQL implementation (with a library and a single line of code)
  • Get most of the benefits of GraphQL on the backend and frontend, while using and exposing REST
  • Support all your existing clients with REST while improving your backend stack with GraphQL
  • Create custom, perfectly client-aligned REST endpoints for your frontend simply by naming a route and attaching a query
  • Stop arguing about REST vs GraphQL. Use GraphQL, generate REST and get the best from both
  • In the other way around (REST to GraphQL) you won’t get the best of both world but less powerful, harder to maintain server implementation with some of the benefits of GraphQL. It is a good and fast start for a migration though..

Wait, WHAT!?

Many articles have been written about the pros and cons of GraphQL and REST APIs and how to decide which one to use. I’m not going to repeat those here..

Then I could get the best of both worlds!

The more I dived into the idea and implementation then more I realized it’s not only that we can have both types of APIs created for us, but even if we just want to expose REST APIs, and none of our clients use GraphQL, GraphQL is the best way the create REST APIs!

How does the above sentence even make sense?!

Usually when we (The Guild) help companies and organizations to modernize their APIs, the first to understand the benefits of GraphQL are the frontend developers, for obvious reasons. But as soon as the backend developers “Get it”, they become the biggest advocates of the technology. But they still need to support existing clients and 3rd party partners.

  • Truly RESTful API out of the box
  • GraphQL Subscriptions as Webhooks
  • Runtime validation of data — be 100% sure that fetched data matches schema’s and query’s structure. You send exactly what I want to send, string is a string, an object has exactly the same properties.
  • Creating a custom endpoint is now a matter of choose a route name and attaching a query to it. done. No more manual work of creating and maintaining client specific endpoints!
  • Use GraphQL’s philosophy of evolving APIs through schemas — no more painful V1 — V2 API migrations.
  • Use modern technology that is easier to hire people to. Companies like Facebook, Airbnb and others have moved to GraphQL. None of them has gone back.
  • The power of GraphQL resolvers to create your API implementation, instead of manually written controllers from MVC
  • GraphQL allows you to easily share data across every resolver, we call it Context.
  • Forces you to define and resolve data in an opinionated way that actually helps building an API. It runs functions in parallel (functions that are nested at the same level), handles async and at the end, it is responsible of merging all of that into a single object, so you don’t have to think about it.

Sofa — Use GraphQL to create RESTful APIs

So we created Sofa (pun intended), an open source library you install on your GraphQL server to create a fully RESTful and configurable API gateway. Use GraphQL to REST.

“How to” tutorial

Let’s create a short step by step tutorial on how to create a RESTful API.

Why did you do that for!?!?

Gradually migrating from old REST implementations

This is actually a good direction to go. In many of the companies we work with, they’ve created REST API layers using old technology on top of their original web-services.


Give me more details

Sofa uses Express by default but you can use any other server framework. Sofa is also GraphQL server implementation agnostic.

How Sofa works?

Under the hood, Sofa turns each field of Query and Mutation types into routes. First group of routes is available only through GET method, mutations on the other hand get POST.

GraphQL Subscriptions as Webhooks?

The way it works is simply, you start a subscription by calling a special route and you get a unique ID that later on might be used to update or even stop the subscription. Subscriptions are Webhooks. Sofa knows exactly when there’s an even happening on your API and notifies you through the endpoint you’ve assigned a subscription to.

Models / Resources?

In some cases you don’t want to expose an entire object but just its id. How you’re able to do that with Sofa? You need to have two queries. First one has to return a single entity based just on its id (which would be an argument) and the second one should resolve a list of those. Also the names should match, for example a resource called User should have two queries: user(id: ID): User and users: [User]. Pretty much the same thing you would do with REST.

type Query {
user(id: ID!): User
users: [User]
}
type Book {
id: ID
title: String!
author: User!
}
extend type Query {
book(id: ID!): Book
books: [Book]
}
sofa({
...,
ignore: ['Book.author'],
})

Swagger and OpenAPI

Thanks to GraphQL’s type system Sofa is able to generate always up-to-date documentation for your REST API. Right now we support Swagger and its OpenAPI specification but it’s really easy to adopt different specs.

Summary

sofa-api makes it extremely easy to create a RESTful API with all the best practices of REST from a GraphQL server using all its power.

The Guild

The Guild

Thanks to Kamil Kisiela

Urigo

Written by

Urigo

Founder of The Guild; Ex Core Dev at @apollographql & @meteorjs; https://github.com/urigo ; https://www.angular-meteor.com/; uri.goldshtein@gmail.com

The Guild

The Guild

The Guild

Urigo

Written by

Urigo

Founder of The Guild; Ex Core Dev at @apollographql & @meteorjs; https://github.com/urigo ; https://www.angular-meteor.com/; uri.goldshtein@gmail.com

The Guild

The Guild

The Guild

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store