Build Your Web Projects With REST APIs

Prepare to Design Your Own REST API

Now that you've seen how to use a third-party API, let's talk more about when and how you would actually want to build a REST API yourself. 

There are two main reasons you would have for developing your own API:

1. If you are building your own web or mobile app for cooking recipes, you know you'll need to save and manipulate a lot of data. 👨‍🍳🍳 You would definitely need a database, but you don't want front-end developers to have to know SQL in order to display the information on your UI. You also want to follow web application standards, so there is an API layer between your database and access to your data. You don't want just any developer to be able to query your database directly (for security and privacy concerns). And you want a quick and efficient way to search and query existing data. You'd need an internal API for that. 

2. If you are building a web or mobile app where you want other developers to interact with your data. For example, an application where you collect information about your favorite TV show characters, and you want other developers to be able to add to and use the data you are gathering. 

Building Is Simple, Designing Is Work! 

Like anything involving complexity, a thoughtful and intelligent design is key to achieving long-term success. It may be easy to start building right away, but before you warm up your typing fingers, you need to think about key design concepts that will make your API user-friendly and scalable. 

Let’s go step by step. Start by asking yourself about important functionality you need to use with your API:

• What kind of endpoints will you need? 

• What resources do you need to create?

• What resources will you need to perform CRUD operations on?

• Do you need all four CRUD operations for each resource? Or just one or two? 

Once you've answered these questions, you're ready to start prepping your documentation.

Document All Day: Why Proper Documentation Is Key

Absolutely not! In previous chapters, we consulted the GitHub documentation to use the API properly. Without all of the information, we would have struggled to use the right endpoint or know which parameters to specify. Documentation is one of the most important aspects of APIs! When you create an API, you will also need to consider the other developers using it. That means having good documentation so they can easily understand what your API should be able to do and how to use it.

As you saw with the GitHub documentation, there is a lot of information that needs to be explained to your API user, including:

1. Descriptions of the API resources.

2. The available URIs and HTTP verbs, along with what they do.

3. The parameters (if any) that need to be given to the endpoint.

4. A request example. 

5. A typical response for the given request.

Every API handles documentation a little differently, but here are some good examples:

Stripe API Documentation 

In the Stripe API, you can clearly see that the documentation describes the resource URL and relevant information that developers need to understand.

The documentation also shows an example response to API requests: 

Pinterest API Documentation 

The Pinterest API has a good example of showing an HTTP verb, URI, parameters, and a description of what the endpoint does.

Documentation provides information about endpoints and requests but should also document error handling.

Handle Those Errors 🙅‍♀️

As you’ve seen in previous chapters, requests may be either successful or unsuccessful for many different reasons: resource not found, server unavailable, etc. Your API should also have proper error handling. If a developer accidentally tries to use your API for something they shouldn't (incorrect authentication or unnecessary letters added to a request), your API should tell the user what they did wrong so they can correct it. Everyone makes the occasional typo from time to time! The HTTP code provides information about the type of error but is usually also accompanied by an error message in the message body.  

You saw what some errors looked like in the GitHub API when we were updating a repository in the last part. When we tried to make a request without our authentication code, the response back was:

{
 "message": "Requires authentication",
 "documentation_url": "https://developer.github.com/v3/repos/#edit"
}

That's how we knew that we forgot our authentication code in the first place! There are many different types of errors that can come up in your API that when handled correctly, can make developers’ lives easier when using your API. 💪

Meetup's API has a good example of all the different errors that can come up when you use their API and what they mean:

All the possible errors from the Meetup API

An essential part of designing your API needs to be thinking about possible ways users can misuse it! Then depending on the error, you can send back the appropriate message in the response.

Let’s Recap!

• You can build an API either to use within your own application or for external developers to interact with your data.

• It's important to design an API and think about all the necessary functionality before you start building. 

• Documentation and proper error handling are essential for other developers to understand your API. 

Now that you know the basics, it’s time to design your API endpoints. Cool, but how? That’s what you’ll see in the next chapter.