A Beginner’s Guide to RESTful APIs

Table of Contents

• Meet the Expert: Rich Greenhill
• What is an API?
• What does REST stand for?
• The 4 Design Principles of REST APIs
• REST vs HTTP
• Web APIs vs REST APIs
• Getting Started: How to Create & Use Your Own REST APIs
• Rich’s Favorite REST API Resources for Beginners

REST APIs are relied upon by today’s software engineers and are a cornerstone of the web. But what is a REST API and how exactly is it used on the job? From general concepts to the core principles, Rich Greenhill of Thinkful breaks down the inner workings of REST APIs. Find out what it takes to create and use REST APIs, and how the Software Engineering curriculum at Thinkful prepares students to use REST APIs in their first jobs! 

Meet the Expert: Rich Greenhill

• Rich is a Software Engineering Bootcamp Instructor at Thinkful. 
• Rich teaches Full Stack JavaScript, React, and Node.js, and provides his students the guidance and support they need to transition from coding newbies to software engineers.

What is an API?

API stands for Application Programming Interface. There are many types of APIs used today, but the term is also commonly used to refer to an internet-connected data service. APIs are the communication between two computer systems. They also generate boundaries on how they may be used within a library.  

How do software engineers use APIs?

Software engineers are responsible for devising the interface for two systems to communicate with one another. A software engineer may develop a small internal library or even a single file, then they can offer this API to other software engineers so they can utilize it. Ultimately, it’s up to the author of an API to determine what information is accessible. 

It’s nearly essential that new software engineers understand REST APIs. An understanding of REST APIs applies to any kind of web application development position because they are so prevalent in the world of web-based data services. New software engineers should have a basic awareness of:

• How to identify a RESTful API (because will affect many areas of project work); and
• How to fetch and create data on that service.

In a more traditional software development role such as a non-network-connected application or gaming app that is not making network requests, it may not be so important to understand REST APIs. 

What does REST stand for?

REST stands for Representational State Transfer. 

• Representational State is a state of conversion from its constant state (also known as its source of truth format) into the appropriate format for that client. 
• Transfer is the actual transfer of that data. 

REST is both the interface and a set of standards and principles that offers uniformity of an interface between two systems. REST evolved with web development as web pages went from static and non-interactive to rich, interactive web applications that needed multiple data services to transfer that information. REST follows a set of principles used to design something new on the web or update an interface between two systems on the web. 

The counterpart to Representational State is Constant State, which is simply the source where data is stored in a particular format, such as a SQL database where the actual storage of data is in a table format. However, when a client or team needs data in a different format, we call this temporarily generated version of data its represented state. For example, an Internet of Things (IoT) device may only need a partial record from a database in a format different to SQL.

What does it mean for an API to be “RESTful?”

Since uniformity is a key part of REST, RESTful APIs are predictable. With its set of standards and principles, a software engineer can generally know what to expect from a RESTful API. A software engineer just needs to identify which resources the RESTful API is offering and then they understand quickly how to retrieve what they need – that could be a collection of data, a single data point, or a filtered collection. 

If the API is not RESTful, then a software engineer will have to read the full documentation to understand the interface in order to retrieve the data they seek. 

The 4 Design Principles of REST APIs

1. Uniform interface - The most well-known, common reason to adopt REST is its core principle of uniform interface.
2. Statelessness - Each request made is treated as an individual, open/close request. This simple, transactional approach reduces risk for bugs but means you have to make constant authentication requests, proving yourself every time you make a request.
3. Layered System - A REST API provides a layered system of client, communication interface, and back end storage/persistent storage.
4. Optimization - REST APIs are used for optimizing network requests. On the job, this means that a software engineer can ask for a response and if nothing has changed since the last time they asked for it, they can use what is kept in their cache without having to reload.

REST vs HTTP

REST and HTTP were created in the same era of computer history. REST and HTTP actually work together in a system, but are not the same. 

HTTP stands for Hypertext Transfer Protocol. An HTTP request can be thought of like a mobile phone text message between two people, except it's one machine sending a message to another and it must follow a specific format that includes a status line, headers, and an optional body of data. Two primary types of requests are:  

• GET request, which cannot manipulate or mutate data in any way. 
• POST request, which must indicate the creation of data.

While REST also allows two machines to communicate with each other over the web, REST has further restrictions. A REST API includes the additional guidelines as detailed in the rest of the doc, such as uniformity, represented state, etc. 

Web APIs vs REST APIs

Web APIs and HTTP APIs are interchangeable. REST may apply to a web API, but since REST is a set of principles, it can apply outside of web-based APIs. 

How does a Web API actually work?

In the context of web APIs, to make a request over the web, we use HTTP. Using HTTP enforces that every request a software engineer makes is delivered in two parts: 

1. Method - A method is one of a preset list of verbs  (e.g. GET, POST).
2. Path - A path indicates the resource in a domain. Think of the domain as the physical location of a house, and the path may be the individual file in a drawer in a room of a house. In a URL, the path is separated from the domain by the slash (for example: www.coursereport.com/coding/2021/10/01/todays-blog). 

Here is an example HTTP request made up of a status line, headers, and no data body:

GET /blog HTTP/1.1
Host: coursereport.com
Connection: keep-alive
Accept: text/html

Getting Started: How to Create & Use Your Own REST APIs

Learning how to create and use your own REST APIs requires a bit of foundational knowledge. That said, in the grand scope of computer science concepts, RESTful APIs are a relatively lightweight thing to study, practice, and use daily. To get started on learning REST APIs:

• Know your fundamentals - You will need to build an API in a programming language. Simply understanding the foundations of JavaScript, for example, will be enough to prepare you to build and consume RESTful APIs.
• Understand databases - An API that is managing resources for you will need some persistent data storage, so you should have an understanding of how databases work. At Thinkful, we currently teach how to manage and use a SQL database. 

There are an array of programming languages you can use to build an API. Whether a back end developer builds an API to be used as a data service for other developers or a front end developer consumes an API that someone else has written, the programming language for a REST API is pretty agnostic. That said, as an API beginner, choose a programming language, like JavaScript. With this language, you will be sending instructions to your machine to make specific calls.

Learning REST APIs at Thinkful

Thinkful offers an immersive Software Engineering Bootcamp that teaches everything you need to know to get started using REST APIs. At Thinkful, we begin with an assumption that our students have no programming knowledge, and we offer all the tools needed to help our students build a website from scratch:

• We start by diving into programming fundamentals, such as broad core concepts of programming and JavaScript. 
• We tackle the front end web, and students learn how to apply what they’ve learned to building web interfaces, such as applying interactive components (click, slide, drag, etc) to a blank web page. 
• Then we move to the back end to start building RESTful APIs. Students have already consumed RESTful APIs from their front end app without fully understanding it! This is because we provide functions that make HTTP requests from our prebuilt API, which will send data to their frontend applications to populate on the web page. 
• After learning to build the API layer, students are then introduced to databases to create a persistent storage layer for their application.  The API sits as a controller between the frontend and the database.
• The final section of the course focuses on core computer science concepts, including low level data structures and algorithms for sorting and searching. 

Rich’s Favorite REST API Resources for Beginners

To get to know RESTful principles and their applications to software engineering, a good reference point is  GitHub's JSON API. GitHub documentation follows the RESTful principles and is really easy to dive into. The Json API specs go deeper into using RESTful principles with the JSON data format. JSON is platform-agnostic and uses a text format with a specific syntax for sending richer data, like numbers, arrays, and nested objects across any systems. Some libraries have prebuilt REST APIs, so you could also practice front end coding without having to build and customize a REST API. Libraries can act as a test bed for front end client code that you want to try. 

Find out more and read Thinkful reviews on Course Report. This article was produced by the Course Report team in partnership with Thinkful.