Learn the basics of APIs and what makes an API "RESTful"

So what is an API (Application Programming Interface)?

An API is a set of rules that allow one piece of software to talk to another.

It's pretty simple from a high-level — two applications interfacing (or “talking”) with each other via programs. APIs also make our lives easier by abstracting away complex code and replacing it with simpler, more straightforward code.

For example, think about what happens when you open a music streaming app and play a song.

There's probably some code that runs when you hit play that looks something like this:

 function is an API method that abstracts away things like:

As developers, we don't need to know or care about the lower-level code when we call the 

 method, and that's fine! APIs are here to make our lives easier.

In JavaScript, APIs are usually based on 

Let's take a look at a more common example you've probably encountered before. If you've ever written JavaScript like this:

const element = document.querySelector('.special-class');

Here, the document object is being used as the 

Note that these APIs aren't part of the JavaScript language, but rather they're 

 to give developers a convenient set of tools out of the box.

In the web development world, APIs generally fall into two categories:

Usually, when people talk about third-party APIs like the Spotify API or the GitHub API, they’re talking about 

So if an API is a set of rules that allow one piece of software to talk to another, then REST (Representational State Transfer) is a

standard set of rules that developers follow to create an API. 

Six conditions that need to be met for an API to be considered RESTful:

I think you’d be hard-pressed to find anyone who remembers the definition of each of these conditions off the top of their head, so the gist of it is this:

In a nutshell, you should be able to receive a piece of data (a.k.a. 

) when you access a predefined URL. Each of these URLs, also known as “

, and the data you receive from the request is called a 

. The data provided by these responses are usually in the form of JSON (

A RESTful request is composed of four parts:

Let’s take a quick look at what each of these four parts are.

 (also known as the "root" endpoint). For example, the base URL of Spotify's API is 

. Additionally, each endpoint in a REST API has a 

 that determines the resource being requested.

Endpoints are just like any other URL you visit on the web, but instead of returning data for a website, they return resources (e.g. data like JSON)

 you send to the server. There are five common types of HTTP methods: 

. They are used to perform four possible operations: Create, Read, Update, or Delete (CRUD).

When working with a REST API, the documentation should tell you which HTTP method to use with each request.

 that are used to provide information to both the client and server. You can store things like authentication tokens, cookies, or other metadata in HTTP headers. 

For example, the header below tells the server to expect JSON content.

You can find a complete list of valid headers on 

 information you want to send to the server

 and is normally transmitted in the HTTP request's body by sending a single 

This information is usually the data you'd like to create a new resource with (with a POST request) or the modified value of a resource you'd like to update (with a PUT or PATCH request). 

 requests don't need any extra information from you to return existing resources, only 

Now that we know the parts of an HTTP request, let’s take a look at what is returned in an HTTP response: the status code and the body data.

Responses always include an HTTP status code in the response header. These status codes are numbers that indicate whether a request was successfully completed and range from the 100s to the 500s.

Similar to HTTP requests, responses usually return body data in the form of 

To wrap it all up, let’s take a look at a real-world example with the 

Spotify’s Web API, which has a base URL of 

, you'll see that the  HTTP request’s endpoint (

https://api.spotify.com/v1/playlists/{playlist_id}

. It also requires a path parameter of the playlist’s ID.

https://api.spotify.com/v1/playlists/59ZbFPES4DQwEjBpWHzrtC

, the API's response will include body data that look like this:

{
    "collaborative": false,
    "description": "Having friends over for dinner? Here´s the perfect playlist.",
    "external_urls": {
        "spotify": "http://open.spotify.com/user/spotify/playlist/59ZbFPES4DQwEjBpWHzrtC"
    },
    "followers": {
        "href": null,
        "total": 143350
    },
    "href": "https://api.spotify.com/v1/users/spotify/playlists/59ZbFPES4DQwEjBpWHzrtC",
    "id": "59ZbFPES4DQwEjBpWHzrtC",
    "images": [
        {
            "url": "https://i.scdn.co/image/68b6a65573a55095e9c0c0c33a274b18e0422736"
        }
    ],
    "name": "Dinner with Friends",
    ...
}

This JSON includes things like the playlist’s number of followers, the URL of the cover image, the playlist’s name, and much more.

Now that you have a solid understanding of REST APIs, try interacting with one yourself!

Be sure to check out our new course being released soon, 

, where we apply these concepts to build a real-world, full stack web app!

<h1 data-node-type="titlePlaceholder" class="titlePlaceholder">5 Minute Intro to REST APIs</h1><div data-node-type="summary" class="summary-block">Learn the basics of APIs and what makes an API "RESTful"</div><p>So what is an API (Application Programming Interface)?</p><div data-panel-type="info" data-panel-position="inline" class="panel panel-type-info panel-position-inline"><div class="panel-container lolwut"><p>An API is a set of rules that allow one piece of software to talk to another.<strong> </strong></p></div></div><p>It's pretty simple from a high-level — two applications interfacing (or “talking”) with each other via programs. APIs also make our lives easier by abstracting away complex code and replacing it with simpler, more straightforward code.</p><p>For example, think about what happens when you open a music streaming app and play a song.</p><figure class="photo figure-position-inline"><img src="https://s3.amazonaws.com/assets.fullstack.io/n/20210724185845966_Screen%20Shot%202021-07-22%20at%2011.11.51%20PM.png" attachmentid="580b0884-37dc-40a4-962d-53091a1767b8" contenteditable="false" data-width="2098" data-height="778"><div></div></figure><p>There's probably some code that runs when you hit play that looks something like this:</p><textarea data-iscodemirror="true" data-mode="javascript" data-uniqueid="cm-DuFpX" id="cm-DuFpX">mediaPlayer.play();</textarea><p>That <code>play()</code> function is an API method that abstracts away things like:</p><ul><li><p>The code needed to retrieve the audio file from the internet or your device</p></li><li><p>The code needed to send audio data to your device</p></li></ul><p>As developers, we don't need to know or care about the lower-level code when we call the <code>play()</code> method, and that's fine! APIs are here to make our lives easier.</p><p></p><h2 class="heading-anchor-text" id="how-do-apis-work?"><span>How do APIs work?</span><a class="d-inline heading-anchor" title="Direct link to heading" href="#how-do-apis-work?">#</a></h2><p>In JavaScript, APIs are usually based on <strong>objects</strong>. In the example above, the <code>mediaPlayer</code> object is the <strong>entry point</strong> for the API, and <code>play()</code> is the <strong>API method</strong>.</p><p>Let's take a look at a more common example you've probably encountered before. If you've ever written JavaScript like this:</p><textarea data-iscodemirror="true" data-mode="javascript" data-uniqueid="cm-tS0Zj" id="cm-tS0Zj">const element = document.querySelector('.special-class');</textarea><p>then congrats, you've used the <a href="https://developer.mozilla.org/en-US/docs/Web/API/Document_Object_Model" rel="noopener noreferrer nofollow">DOM (Document Object Model) API</a>!</p><p>Here, the document object is being used as the <strong>entry point</strong> for the DOM API, and <code>querySelector()</code> is the <strong>API method</strong>.</p><figure class="photo figure-position-inline"><img src="https://s3.amazonaws.com/assets.fullstack.io/n/20210724190517435_dom-api.png" attachmentid="2957792d-56dd-430e-8e90-e40644cc910f" contenteditable="false" data-width="700" data-height="200"><div></div></figure><div data-panel-type="info" data-panel-position="inline" class="panel panel-type-info panel-position-inline"><div class="panel-container lolwut"><p>Note that these APIs aren't part of the JavaScript language, but rather they're <strong>built on top of JavaScript</strong> to give developers a convenient set of tools out of the box.</p></div></div><p></p><h2 class="heading-anchor-text" id="two-types-of-apis"><span>Two Types of APIs</span><a class="d-inline heading-anchor" title="Direct link to heading" href="#two-types-of-apis">#</a></h2><p>In the web development world, APIs generally fall into two categories:</p><ol><li><p><strong>Browser APIs</strong></p><p>Browser APIs (like the DOM API) are built into your web browser and expose data from the browser and surrounding computer environment that developers can easily leverage.</p></li><li><p><strong>Third-party APIs</strong></p><p>On the other hand, third-party APIs (like the <a href="https://developer.twitter.com/en/docs/twitter-api" rel="noopener noreferrer nofollow">Twitter API</a> or the <a href="https://developer.spotify.com/documentation/web-api/" rel="noopener noreferrer nofollow">Spotify API</a>) are not built into the browser by default, and you have to retrieve their information from somewhere on the web.</p></li></ol><div data-panel-type="info" data-panel-position="inline" class="panel panel-type-info panel-position-inline"><div class="panel-container lolwut"><p>Usually, when people talk about third-party APIs like the Spotify API or the GitHub API, they’re talking about <strong>REST APIs</strong>.</p></div></div><p></p><h2 class="heading-anchor-text" id="regular-apis-vs-rest-apis"><span>Regular APIs vs. REST APIs</span><a class="d-inline heading-anchor" title="Direct link to heading" href="#regular-apis-vs-rest-apis">#</a></h2><p>So if an API is a set of rules that allow one piece of software to talk to another, then REST (Representational State Transfer)&nbsp;is a<strong> </strong>standard set of rules that developers follow to create an API. </p><div data-panel-type="info" data-panel-position="inline" class="panel panel-type-info panel-position-inline"><div class="panel-container lolwut"><p>REST is a set of rules that determine <strong><em>what an API looks like</em></strong>.</p></div></div><p>Six conditions that need to be met for an API to be considered RESTful:</p><ol><li><p>Client-Server</p></li><li><p>Stateless</p></li><li><p>Cacheable</p></li><li><p>Uniform Interface</p></li><li><p>Layered</p></li><li><p>Code-on-demand</p></li></ol><p>I think you’d be hard-pressed to find anyone who remembers the definition of each of these conditions off the top of their head, so the gist of it is this:</p><ul><li><p>When an application makes an HTTP request to a URL hosted by a server, the server should return a response with some data.</p></li><li><p>All requests should be independent of each other. It should be possible to make two or more HTTP requests in any order, with the same responses being received.</p></li><li><p>There should be a uniform interface between components so that information is transferred in a standard form (e.g. API methods)</p></li></ul><p></p><h2 class="heading-anchor-text" id="restful-requests"><span>RESTful Requests</span><a class="d-inline heading-anchor" title="Direct link to heading" href="#restful-requests">#</a></h2><p>In a nutshell, you should be able to receive a piece of data (a.k.a.&nbsp;<strong>resource</strong>) when you access a predefined URL. Each of these URLs, also known as “<strong>endpoints</strong>", are part of what is called a <strong>request</strong>, and the data you receive from the request is called a <strong>response</strong>. The data provided by these responses are usually in the form of JSON (<a href="https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Objects/JSON" rel="noopener noreferrer nofollow">JavaScript Object Notation</a>).</p><p>A RESTful request is composed of four parts:</p><ol><li><p>The endpoint URL</p></li><li><p>The HTTP method</p></li><li><p>The HTTP headers</p></li><li><p>The body data</p></li></ol><p>Let’s take a quick look at what each of these four parts are.</p><h3 class="heading-anchor-text" id="1-the-endpoint"><span>1. The endpoint</span><a class="d-inline heading-anchor" title="Direct link to heading" href="#1-the-endpoint">#</a></h3><p>The "endpoint" is the URL you request.</p><p>All REST APIs have a <strong>base URL</strong> (also known as the "root" endpoint). For example, the base URL of Spotify's API is <code>https://api.spotify.com</code> while the base URL of GitHub's API is <code>https://api.github.com</code>. Additionally, each endpoint in a REST API has a <strong>path</strong> that determines the resource being requested.</p><figure class="photo figure-position-inline"><img src="https://s3.amazonaws.com/assets.fullstack.io/n/20210724190832835_endpoint.png" attachmentid="c602cf71-a9bd-4967-97b6-66d211958914" contenteditable="false" data-width="700" data-height="200"><div></div></figure><p>In the example endpoint above, <code>https://api.spotify.com/v1</code> is the base URL, and <code>/playlists/59ZbFPES4DQwEjBpWHzrtC</code> is the path to a particular playlist.</p><div data-panel-type="info" data-panel-position="inline" class="panel panel-type-info panel-position-inline"><div class="panel-container lolwut"><p>Endpoints are just like any other URL you visit on the web, but instead of returning data for a website, they return resources (e.g. data like JSON)</p></div></div><h3 class="heading-anchor-text" id="2-the-http-method"><span>2. The HTTP Method</span><a class="d-inline heading-anchor" title="Direct link to heading" href="#2-the-http-method">#</a></h3><p>The HTTP method is the <strong>type of request</strong> you send to the server. There are five common types of HTTP methods: <code>GET</code>, <code>POST</code>, <code>PUT</code>, <code>PATCH</code>, and <code>DELETE</code>. They are used to perform four possible operations: Create, Read, Update, or Delete (CRUD).</p><ul><li><p><strong>GET</strong>: Retrieves or "reads" resources</p></li><li><p><strong>POST</strong>: Creates resources</p></li><li><p><strong>PUT / PATCH</strong>: Updates resources</p></li><li><p><strong>DELETE</strong>: Deletes resources</p></li></ul><p>When working with a REST API, the documentation should tell you which HTTP method to use with each request.</p><h3 class="heading-anchor-text" id="3-the-http-headers"><span>3. The HTTP Headers</span><a class="d-inline heading-anchor" title="Direct link to heading" href="#3-the-http-headers">#</a></h3><p>Headers are <strong>key-value pairs</strong> that are used to provide information to both the client and server. You can store things like authentication tokens, cookies, or other metadata in HTTP headers.&nbsp;</p><p>For example, the header below tells the server to expect JSON content.</p><textarea data-iscodemirror="true" data-mode="javascript" data-uniqueid="cm-Fe1xY" id="cm-Fe1xY">"Content-Type: application/json"</textarea><p>You can find a complete list of valid headers on <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers" rel="noopener noreferrer nofollow">MDN’s HTTP Headers Reference</a>.</p><h3 class="heading-anchor-text" id="4-the-body-data"><span><br>4. The Body Data</span><a class="d-inline heading-anchor" title="Direct link to heading" href="#4-the-body-data">#</a></h3><p>The "body" of a request contains any<strong> information you want to send to the server</strong> and is normally transmitted in the HTTP request's body by sending a single <strong>JSON-encoded data string</strong>.</p><p>This information is usually the data you'd like to create a new resource with (with a POST request) or the modified value of a resource you'd like to update (with a PUT or PATCH request).&nbsp;</p><div data-panel-type="info" data-panel-position="inline" class="panel panel-type-info panel-position-inline"><div class="panel-container lolwut"><p>Note that since <code>GET</code> requests don't need any extra information from you to return existing resources, only <code>POST</code>, <code>PUT</code>, <code>PATCH</code>, or <code>DELETE</code> requests can have body data.</p></div></div><p></p><h2 class="heading-anchor-text" id="restful-responses"><span>RESTful Responses</span><a class="d-inline heading-anchor" title="Direct link to heading" href="#restful-responses">#</a></h2><p>Now that we know the parts of an HTTP request, let’s take a look at what is returned in an HTTP response: the status code and the body data.</p><p>Responses always include an HTTP status code in the response header. These status codes are numbers that indicate whether a request was successfully completed and range from the 100s to the 500s.</p><ul><li><p><strong>100+</strong>: Informational response</p></li><li><p><strong>200+</strong>: Request has succeeded</p></li><li><p><strong>300+</strong>: Request has redirected to another URL</p></li><li><p><strong>400+</strong>: An error that originates from the client has occurred</p></li><li><p><strong>500+</strong>: An error that originates from the server has occurred</p></li></ul><p>Similar to HTTP requests, responses usually return body data in the form of <strong>JSON</strong>.</p><p></p><h2 class="heading-anchor-text" id="rest-apis-in-the-wild"><span>REST APIs in the wild</span><a class="d-inline heading-anchor" title="Direct link to heading" href="#rest-apis-in-the-wild">#</a></h2><p>To wrap it all up, let’s take a look at a real-world example with the <a href="https://developer.spotify.com/documentation/web-api/" rel="noopener noreferrer nofollow">Spotify API.</a></p><p>Spotify’s Web API, which has a base URL of <code>https://api.spotify.com/v1</code>, has an endpoint that lets you <a href="https://developer.spotify.com/documentation/web-api/reference/#endpoint-get-playlist" rel="noopener noreferrer nofollow">get a playlist by its ID</a>.</p><figure class="photo figure-position-inline"><img src="https://s3.amazonaws.com/assets.fullstack.io/n/20210724190251588_Screen%20Shot%202021-07-24%20at%202.35.44%20PM.png" attachmentid="3f99b8db-1777-4b36-b055-421366803802" contenteditable="false" data-width="2850" data-height="1184"><div></div></figure><p>If you take a look at the <a href="https://developer.spotify.com/documentation/web-api/reference/#endpoint-get-playlist" rel="noopener noreferrer nofollow">docs</a>, you'll see that the  HTTP request’s endpoint (<code>https://api.spotify.com/v1/playlists/{playlist_id}</code>) requires a <code>GET</code>&nbsp;<strong>HTTP method</strong> and must have a valid Authorization <strong>header</strong>. It also requires a path parameter of the playlist’s ID.</p><p>So if you send a&nbsp;<code>GET</code> request to <code>https://api.spotify.com/v1/playlists/59ZbFPES4DQwEjBpWHzrtC</code>, the API's response will include body data that look like this:</p><textarea data-iscodemirror="true" data-mode="javascript" data-uniqueid="cm-nwXf6" id="cm-nwXf6">{
    "collaborative": false,
    "description": "Having friends over for dinner? Here´s the perfect playlist.",
    "external_urls": {
        "spotify": "http://open.spotify.com/user/spotify/playlist/59ZbFPES4DQwEjBpWHzrtC"
    },
    "followers": {
        "href": null,
        "total": 143350
    },
    "href": "https://api.spotify.com/v1/users/spotify/playlists/59ZbFPES4DQwEjBpWHzrtC",
    "id": "59ZbFPES4DQwEjBpWHzrtC",
    "images": [
        {
            "url": "https://i.scdn.co/image/68b6a65573a55095e9c0c0c33a274b18e0422736"
        }
    ],
    "name": "Dinner with Friends",
    ...
}</textarea><p>This JSON includes things like the playlist’s number of followers, the URL of the cover image, the playlist’s name, and much more.<br></p><h2 class="heading-anchor-text" id="next-steps"><span>Next Steps</span><a class="d-inline heading-anchor" title="Direct link to heading" href="#next-steps">#</a></h2><p>Now that you have a solid understanding of REST APIs, try interacting with one yourself!</p><h3 class="heading-anchor-text" id="coming-soon"><span>Coming Soon!</span><a class="d-inline heading-anchor" title="Direct link to heading" href="#coming-soon">#</a></h3><p>Be sure to check out our new course being released soon, <strong>Build a Spotify Connected App</strong>, where we apply these concepts to build a real-world, full stack web app!</p><p></p><h2 class="heading-anchor-text" id="sources"><span>Sources</span><a class="d-inline heading-anchor" title="Direct link to heading" href="#sources">#</a></h2><ul><li><p><a href="https://www.youtube.com/watch?v=GZvSYJDk-us" rel="noopener noreferrer nofollow">freeCodeCamp's APIs for Beginners course</a></p></li><li><p><a href="https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Client-side_web_APIs/Introduction" rel="noopener noreferrer nofollow">MDN's Introduction to Web APIs</a></p></li><li><p><a href="https://www.redhat.com/en/topics/api/what-is-a-rest-api" rel="noopener noreferrer nofollow">https://www.redhat.com/en/topics/api/what-is-a-rest-api</a></p></li><li><p><a href="https://www.smashingmagazine.com/2018/01/understanding-using-rest-api/" rel="noopener noreferrer nofollow">https://www.smashingmagazine.com/2018/01/understanding-using-rest-api/</a></p></li></ul><p></p>

Learn

The newline Guide to Building Your First GraphQL Server with Node and TypeScript

Teach

Amelia Wattenberger

Author of Fullstack D3

Community

5 Minute Intro to REST APIs

Tags

Responses (0)

Masterclasses

Tutorials

Fullstack React with TypeScript