Build Your Web Projects With REST APIs

Until now, we've only looked at basic endpoints for getting a list of resources or perhaps a single resource by the ID. But there is so much more that is possible with APIs! 💪 Depending on the way you design your URIs, you can create more complex queries like searching, sorting, and more. Let's go back to the InstaPhoto application 📸 to decide what kinds of complex URIs you'll need.

Filter

What if you want your users to be able to search for pictures in specific locations? That's where filtering comes in! You could design an endpoint like:

GET /photos?location={locationId}

That ? is new! The question mark is a way for the API to know you are passing a parameter. A parameter is a piece of data that will be manipulated and used in a certain way by the relevant client, server, or program: in this case, the API. It allows you to create a query that can change depending on the search term. You want the users to be able to search for the location equal to  = locationId. This way, you can write any location ID in the query parameter, and you'll see photos in that location. 🙏🌍   

That's a fair point. Yes, URIs are the resource path, and an endpoint is the domain name plus the resource path.

Search

Search lets you query a list of resources that match your search request. Let's say you want to have an endpoint where users can search for all the photos that have anything to do with snowboarding  🏂. Your endpoint could be:

GET /photos?search=snowboard

If you've ever used search functionality on Twitter, you've seen their search API works very similarly!

This question is common and comes down to the process of how an element is found. For filtering, you start from a smaller, more specific element and collect all the items that match that value. Say you’re searching for all comedy series that start with the letter C – in this instance, you’re filtering.

Searching is a broader approach and widens your scope to anything associated with a certain value.

Sort

Let's say you want your users to see all their followers in alphabetically ascending order by the last name. That’s quite complicated. You can make an endpoint for that!

GET /users/{userId}/followers?sort=lastName&order=asc

The & is new here - it lets you chain different queries together! For example, you can sort the users by lastName and in ascending order. You’ll have already seen sorting in daily web browsing. Usually, you want to see the most recent posts on Twitter or Instagram - which is date sorting!

You can chain all different types of queries together. For example, if you want to see all the verified users with the firstName Jamie, you can query:

GET /users?verified=true&firstName=Jamie

If you want to see all the photos taken in New York City posted on New Year’s Eve with more than 5,000 likes, you can query:

GET /photos?location=NYC&created_at=2021-12-31&likes_greater_than=5000 

And you could add even more queries if you wanted! ✨

For these options to work, you would need to set up this endpoint functionality using the coding language you chose for your application; none of these are built into an API when you create it. This example illustrates some of the possible ways you can use advanced querying in your API.

Paginate Your Results

InstaPhoto 📸 has taken off and become super successful! 🙏 But now, you have thousands of photos in your database, so your /photos endpoint has become very slow, much to the frustration of your users. 😰 What to do? The way to fix that is through something called pagination. It means that your endpoints return only a limited amount of entries on a page number in your response. You can decide how many items you'd want on each page, but usually, they range from 10-100. 

Basically, /photos returns all of the photos on your app. So instead of querying /photos, you'd need to query: 

GET /photos?page=23 

That way, you'll only get the 23rd page of photos, which is maybe 100 in total, instead of all of them. Loading times will be reduced, and your users will be delighted! To see more photos, your user will click on a button to load the next page, giving you:

GET /photos?page=24 

And so on! ✨

In the same way, when you search for something on Google, it's not uncommon to get millions of results – so Google just returns one page of the top results, and you can go through the rest to see more.

Google needs to paginate their results to not overwhelm your UI.

Pagination lets your API consumers call only one page of results at a time, so your client or UI won't be overwhelmed with results!

Use Versioning

The last important design tool for APIs is versioning. You want to give your APIs a version so you can easily keep track of changes and make sure your app stays backward compatible. It means you can keep updating your API while also ensuring that people who rely on the older version can keep using it. For example, if you have clients already using version 1 of your API, you can publish version 2. Then the version 1 API consumers can keep using it until they are ready to upgrade to version 2. Developers can version their APIs in two ways:

1. Add a version field in your request header parameters: "accept-version": "1.3"

2. Add a version to your URI: /v1/

The more common approach is to add a /v1 to the beginning of your URI:

GET /v1/photos 

The above are design-based functionalities and what you need to consider when planning what you want in your API. When you actually build it out, you'll need to choose your own language or framework. We'll discuss this in the last chapter.

Let’s Recap!

• Filter, search, and sort are ways to add more complexity to your API requests.

• Pagination helps your API clients and consumers avoid being overloaded with too much data.

• Versioning lets you keep updating your API without breaking anyone's code that already relies on it. 

You’ve come such a long way! You’ve designed your first API and learned about advanced endpoint functionality. But what if you want to code your own API? What frameworks are out there? What languages can you use? We’ll take a quick look at this in the next and final chapter of this course. 🎉