Now that you know that REST APIs act as intermediaries and help developers manipulate data, let's talk about what that data actually looks like.
Use Resources to Represent REST Data
REST data is represented in what is known as resources.
A resource can be any noun-like object that you can use to represent data in your app. You know—a person, place, or thing! 😉 To make it easy, you can see resources as boxes that you sort objects by category, which you’ve labeled so that you know what’s going into them.
Finding it all a bit abstract? That’s the point! You can represent any piece of data in whatever form you want.
Each resource has additional information about the data it contains. For example, consider an app that lists Marvel heroes. One of the resources might be Superhero, and you might have a name, description, superpower, etc., as additional information.
A group of resources is called a collection. These are referred to by the plural form of the resource name. For instance, a Superhero resource would become Superheroes.
Let’s say you’re creating an API for a skateboard store to have an online delivery service. You want your customers to be able to buy skateboards from the website and for your employees to be able to add products and update inventory.
Let’s go step by step to work out the resources, additional information, and the collections.
For a skateboard store, your resources could be:
Customer
Employee
Shopping cart
Skateboard
Inventory
A skateboard resource could include the following additional information: name, brand, ID, price.
So your collections will be:
Resource | Collection |
skateboard | skateboards |
customer | customers |
Cool! You now have your collections, the corresponding resources, and additional information. Let’s keep going with the skateboard store example and follow the journey of a customer request via your API.
When a customer buys a skateboard using your web application, the following takes place:
The API sends the browser (customer) request to the application’s servers for buying a skateboard.
The request updates the inventory so that there is one fewer skateboard.
The request updates the customer order history to add the skateboard to their purchase history. 😁
Amazing! You now know how and in what form to store the data that you want to use in your API via resources and collections. But hold on, how do you access it? How do you know where to retrieve this data?
Access Data With URI & Endpoints
The path that you give your API lets it know exactly where to find the data you want to retrieve. You can think of this as browsing the local files on your computer. You have to go from folder to folder to find your data, and each picture or document you save has its own file path. For example, a photo from your favorite series could be at the file path:
MyComputer/Images/Series/gameofthrones.jpg
REST APIs similarly store data and a URI is the path to get to it.
If a resource is the object that stores your data, you’re going to need a Uniform Resource Identifier (URI) to retrieve this data. Your URI is the way you identify your resource, like a label.
Let's say you were building an API for a website that would present all of the information about Game of Thrones (book or series). The URI that would list all of the characters could be the following:
/characters
If you want to see information about only one character, which is labeled with an ID of 123, your URI would be:
/characters/123
Just like file paths, URIs can also have nested resources. If you want to get the location of where your character lives, your URI would be something like:
/characters/123/location
Progress! However, without the actual website address, the API won't know where to look for the URI in the first place. That's where endpoints come in.
An endpoint is a URL/URI that is part of an API. If a URI is like a file path, then an endpoint is like the whole file address. All you need to do is add your domain name to the beginning of the URI - and you have an endpoint! For example, if the domain name for our app is gameofthrones-information.com, that would give us:
https://gameofthrones-information.com/characters
Hold up – what’s the difference between a URI and a URL?
All URLs are URIs, but not all URIs are URLs 🤯. Your URI identifies a resource, while your URL locates it.
The two often get mixed up, so let’s simplify things with an example. Going back to the Game of Thrones website, if the character of Jon Snow has the ID 890, the URI would be /characters/890. The URL would be https://gameofthrones-information.com/characters/890
A request’s URL is the complete endpoint that you use for your query. It combines your resource’s domain name + the path. Now you know how to access the data you want!
By the way, there’s no need to make your own GoT API – one already exists, and you can check it out at: anapioficeandfire.com. ⚔️
Understand the Difference Between XML and JSON
Once you have the correct endpoint to query, you can get your data. This is where you get the information about the resources you created.
Data is an umbrella term that describes any information you are sending or receiving, while a resource more specifically describes the nouns within that information.
There are two languages REST API data can use: XML and JSON. If an API returns a set of data in XML or JSON, the content will be the same, but the data format will be different.
XML
In XML, every piece of data has a closing and opening tag. There can be nested tags as well:
<tvshows>
<tvshow>
<title>Game Of Thrones</title>
<director>Alan Taylor</director>
</tvshow>
<tvshow>
<title>Peaky Blinders</title>
<director>Otto Bathurst</director>
</tvshow>
</tvshows>You can see an opening tag for the plural collection at the top – tvshows – surrounded by angle brackets < > . The closing tag at the end is the same except with a slash / in front: </tvshows> , which indicates this is a closing tag. Each listed singular resource has the opening tag <tvshow> and the closing tag </tvshow> . Within each resource, there is more information like “title” and “director.”
JSON
JSON stores data in a key-value format with the type of data as the key, followed by a colon : followed by the value of data. JSON data is enclosed in curly braces {} , and each key and value is sent as strings with quotations around them "" .
All of which gives you:
{ "title" :"Game of Thrones"}Arrays, or lists, in JSON have square brackets around them [] . The example below shows how an entire list can be considered as the value for the "tvshows" key. The same above XML data would be represented in JSON as:
{ "tvshows": [
{ "title": "Game Of Thrones",
"director": "Alan Taylor" }, {
"title": "Peaky Blinders",
"director": "Otto Bathurst" } ]
}JSON is generally considered:
Easier to parse with code.
Shorter.
Quicker to read and write for machines.
Very light and effective thanks to its tree structure and simple syntax.
Here are some examples of real-life APIs returning JSON and XML:
As you can see, JSON is the more popular data language, so we'll be using it for the remainder of this course!
Let’s Recap!
A resource is a noun-like object that you use to save data in an API.
A resource can contain additional information in nested resources.
Resources are grouped together in collections and named using a plural.
You can access resources in APIs through URIs.
REST data can come in JSON or XML, but JSON is more common.
And now, let’s review everything you’ve learned with the part 1 quiz.
Once you’ve completed the quiz, we’ll see you in part 2, where we’ll dive into actually using an API!
