• 4 hours
  • Easy

Free online content available in this course.

course.header.alt.is_video

course.header.alt.is_certifying

Got it!

Last updated on 3/30/22

Use REST Resources and Collections

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:

  1. Easier to parse with code.

  2. Shorter.

  3. Quicker to read and write for machines.

  4. Very light and effective thanks to its tree structure and simple syntax. 

Here are some examples of real-life APIs returning JSON and XML:

  • Penguin Random House: XML.

  • Potter API: JSON.

  • Ghibli API: JSON

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!

Ever considered an OpenClassrooms diploma?
  • Up to 100% of your training program funded
  • Flexible start date
  • Career-focused projects
  • Individual mentoring
Find the training program and funding option that suits you best
Example of certificate of achievement
Example of certificate of achievement