• 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 4/2/20

Use REST Resources and Collections

Log in or subscribe for free to enjoy all this course has to offer!

Now that you know that REST APIs help developers save and manipulate data, let's talk about what that data actually looks like.

REST Data: Using Resources

REST data is represented in resources. A resource can be any noun-like type of object that you can use to represent data in your app.  You know, a person, place, or thing! 😉 This is purposely intended to be somewhat abstract, so you can represent any piece of data you need to interact with. To illustrate this, let's say you were building an API for a grocery store to have an online delivery service. You want your customers to be able to buy products on the website, and you want your employees to be able to add products and update inventory.

If you were building an API for a grocery store, your resources could be:

  • Customer

  • Employee

  • Cart

  • Inventory

  • Product

Each resource has additional information about the data you are trying to describe. For example: 

  • An employee resource could have:  first_name,  last_name,  id,  start_date  

  • A customer resource could have:  first_name,  last_name,  number_of_visits,   loyalty_customer  ,  order_history

So when a customer buys a banana from the grocery using your web application, your API will send the request from the browser to the app's servers to buy one banana. This request will update the inventory, so there is one less banana and update the customer order history to add the banana.  🍌 😁

A group of resources is called a collection.  These are referred to by the plural form of the resource name:

Resource

Collection

employee

employees

customer

customers

OK, now you know how you can store the data you want to use in your API - via resources and collections - but how do you access it? 

Uniform Resource Identifiers & Endpoints

If a resource is the object that stores your data, a Uniform Resource Identifier - or URI - is how you access it. A URI is the path that you need to give your API for it to know where the data is you want to retrieve. You can think of this like browsing your own local files on your computer. You have to go from folder to folder to find your data, and each picture or document that you save has its' own file path. For example, your favorite cat picture could be at the file path:

C:/MyComputer/Pictures/CatPics/ilovecats.jpg

REST APIs also store data in a similar way, and a URI is the path to get to it. Let's say you were building an API for a website that would present all of your favorite cat breeds. 😻 You could have an URI that would list all your cats like:

/cats

If you want to just see information about one cat breed, which is labeled with an ID of 123, your URI would be:

/cats/123

Just like file paths, URIs can also have nested resources. If you only want to get the description of the cat breed you're interested in, your URI would be something like:

/cats/123/description

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. 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!

Endpoint
Domain + URI = endpoint

Now you know how to access the data you want! 🙂

XML vs. 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 of the information you are sending or receiving, while a resource more specifically describes the things within that information.

There are two languages REST API data can use: XML and JSON.

In XML, every piece of data has a closing and opening tag. There can be nested tags as well: 

<breeds>
    <breed>
        <name>Abyssinian</name>
        <origin>Egypt</origin>
    </breed>
    <breed>
        <name>Bengal</name>
        <origin>United States</origin>
    </breed>
</breeds>

You can see an opening tag for the collection at the top - breeds  - surrounded by brackets  < >. The closing tag at the end is the same except with a slash  /  in front:  </breeds>.  Each listed resource has the opening tag  <breed>  and closing tag   </breed>. Within each resource, there is more information like name and  origin

JSON stores data in a key-value format with the type of data as the key, 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 "".

{ "breed":"Abysinian"}

Arrays, or lists, in JSON have brackets around them  []. The example below shows how an entire list can be considered as the value for the  breeds  key. The same above XML data would be represented in JSON as:

{ "breeds": [
    {   "name": "Abyssinian", 
        "origin": "Egypt" },
    {   "name": "Bengal", 
        "origin": "United States" }
]}

JSON is generally considered:

  1. Easier to parse with code.

  2. Shorter.

  3. Quicker to read and write for machines.

  4. Support for arrays or lists.

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

  • Penguin Random House: XML.

  • Cat 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.

  • You can access resources in APIs through URIs.

  • REST data can come in JSON or XML, but JSON is more common.

Example of certificate of achievement
Example of certificate of achievement