Build Your Web Projects With REST APIs

Using Super-Powered Endpoints

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.  We'll 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 query parameter. It allows you to create a query that can change depending on the search term. In this case, 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 be able to 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. However, once you start including query parameters in your URIs, developers start referring to them as endpoints as well!

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 dogs 🐶. Your endpoint could be:

GET /photos?search=dogs

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

This is a common question 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. 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. 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. Sorting appears often 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 that were posted on New Years Eve with more than 5,000 likes, you can query:

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

You would need to set up this endpoint functionality using the coding language you choose for your application, none of these are built into an API when you create it. This is just illustrating some of the possibilities of ways you can use advanced querying in your API.

Pagination

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. 😰 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. 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 instead of all of them.

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.

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!

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. This 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 a version 2 of your API. 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

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.