• 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

Build Your Own REST API

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

If You Build it, the REST Will Come

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

Why would I need to build my own REST API? Can't I use one of the thousands you keep telling me about? 🤔

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

  1. If you are building your own web or mobile app, like for cooking recipes, where 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 the standards for web applications so that there is an API layer between your database and access to your data. You don't want just any developer to be able to directly query your database for security and privacy concerns. And you want a quick and efficient way to be able 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 be able 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 with anything that involves 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 more user-friendly and scalable. 

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

You will also need to take into account the other developers using your API. That means having good documentation so they can easily understand what your API should be able to do.

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

  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:

Twitter API Documentation

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

Resource Information in Twitter Documentation
Resource information in Twitter documentation

Twitter API documentation also shows an example response to API requests:

An example response in Twitter docs
An example response in Twitter docs
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.

The Pinterest API is a good example of a URI, parameters, and the description
Pinterest API documentation

Handle Those Errors 🙅‍♀️

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 be able to tell the user what they did wrong so they can correct it. This takes the form of sending an error in the response message. 

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 we got back was:

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

That's how we knew that we forgot to 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 developer's 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 it means:

All the possible errors from the Meetup API
All the possible errors from the Meetup API

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 important for other developers to understand your API.

Example of certificate of achievement
Example of certificate of achievement