REST vs GraphQL for recruiters

REST and GraphQL are both methods of transferring data and constructing APIs. They are both used to build services so that software applications can talk to each other. When a job description talks about building "API Servers", they often mention they are building "RESTful Services" or using GraphQL. Some legacy systems are still using SOAP (which is another older method of transferring data).

As a recruiter, why should you care? Well, GraphQL is quickly catching up to REST in popularity and you are going to start seeing it mentioned in job descriptions and hearing it in conversations with developers and hiring managers.

Fundamentals: what is HTTP

HTTP (hypertext transport protocol) is the dominant protocol of the internet used to serve and consume web pages and web applications. You are reading this blog right now over HTTP, and your browser (probably Chrome, Safari, Firefox or Edge) is communicating with my blog server using HTTP. Got it? It is the underlying technology that REST and GraphQL are typically implemented over.

What is a "Request" in HTTP

A request is just what it sounds like. It is a way to request data over HTTP from a web server. When your browser goes to a web page it makes a "GET" request. So for example, when you go to "google.com" your browser does this:

GET https://google.com

And it returns an HTML web page that your browser renders.

Another type of request is called a "POST". A POST request is a way of pushing a payload of data to a web server. Usually, a POST request is performed when you submit a form on a website. Imagine you submitted a form that captured your first name, last name and email. This is what it might look like:

POST https://iteachrecruiters.com/signup
{
  "email": "aaron@ard.ninja",
  "firstName": "Aaron",
  "lastName": "Decker"
}

Note: that is not exactly how it will be formatted but you get the idea. There is some data that pushed back to the server in a format like JSON or XML.

What is REST?

REST stands for Representational State Transfer. It is best described as an architectural style for building web services and it is based on a PhD dissertation by Roy Fielding. The main idea is that resources served over HTTP should use the protocol verbs in a specific way. What does that mean?

An HTTP "POST" is a type of request.

Here is an example of what an API to create a "Job Posting" would look like:

HTTP POST /job
{
    "name": "Sr UI Developer",
    "description": "BLah Blah Blah",
    "location": "Minneapolis, MN"
}

---

Returns:
{
    "id": 43392
}

Then if you wanted to get this, you would issue a GET under jobs with the Id you got back:

HTTP GET /job/43392

---

Returns:
{
    "id": 43392,
    "name": "Sr UI Developer",
    "description": "BLah Blah Blah",
    "location": "Minneapolis, MN"
}

What is GraphQL

GraphQL is a newer method of transferring data which was developed by engineers at Facebook and has been gaining a lot of popularity lately.

GraphQL requires that you run a GraphQL server with a schema that defines the APIs you are building. A schema is just like a map of what your data looks like and how you can get it.

I used this example in my last post about GraphQL, so I'll use it again here:

GraphQL is called "GraphQL" because you really can query into the data as though it was a graph. Imagine something like candidate tracking software (which you already probably use some type of). You have the following entities:

1. Candidate
2. Recruiter
3. Company
4. JobPosting

Even though your database could be relational, or even the underlying data source could be an API server you can write a query like you are getting data via graph relationships.

Here is an example: You search for for Company X, then you get every job posting that company has posted, and then you get every candidate that has applied to each of these job postings. Graphql makes is very easy to pull back this tree of data. The query could look like:

query {
  company(id: 12345) {
    name
    description
    jobPostings {
      name
      jobTitle
      salaryRange
      datePosted
      applicants {
        firstName
        lastName
        email
      }
    }
  }
}

What comes back is a single Company with every JobPosting for that company and every Candidate that has applied for each of those job postings.

Trust me, that GraphQL version is much easier to write than it would be to write the equivalent SQL query and expose it using a REST endpoint.

Summary

I know that was probably a lot to absorb so let me boil this down into some key data points you can take away.

• APIs are ways for programs to talk to each other
• REST is a way of building APIs
• GraphQL is a new way of building APIs
• GraphQL uses a structured schema
• GraphQL allows you to treat your data as a graph even if it is not stored that way
• They both work over HTTP, HTTP is the underlying transfer protocol of the web.

You can see GraphQL adoption is quickly picking up here in Google Trends: