• 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

Design Your API Endpoints

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

Design a Photo-Sharing API

For this part, we'll be thinking about how to design an API for a photo-sharing app called InstaPhoto. 📸 We want users to be able to post and share photos with their friends, comment on other people's photos, create hashtags, search photos by location, the whole deal.

Some examples of resources you'll definitely need are:

  • /photo

  • /user

  • /location

  • /post

From here you can start thinking about important questions like:

  • Which endpoints will require authorization?

  • Which resources will you want to be able to update?

  • Will you need to be able to edit posts after they are created?

  • Should comments be deletable?

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

There is no right or wrong answer here - it really just depends on the InstaPhoto app you want to build!

Endpoint Design

When designing endpoints, naming is key. You want developers using this to naturally understand what each endpoint is supposed to do. Current naming conventions are to only include the resource you are trying to update, and not the verb you are trying to accomplish. 

You should only use the resource name in the URI because the action is already in the HTTP verb. 

  • POST /photo

  • PUT /photo

  • GET /photo

Because the verb of the action is already included in the HTTP request, it is not necessary when actually designing the endpoints.

Mocking Out Endpoints

Let's look at the possible endpoints for InstaPhoto.

Let's say you want users to be able to create, view, and delete photos - but not edit them once they are posted. All of these would also require authentication, because you don't want users to be able to post, edit, or delete photos that aren't theirs! 🔐

Now, pull out a piece of paper and write out some endpoints for creating, viewing, and deleting photos.  Remember, you might want to specify a particular photo when viewing or creating, right? 😉 Once you're done, scroll down and see if what you have matches my answers! 

Brick wall with
Test it out, then scroll down to see some answers!

You could have the following endpoints:

  • POST /photos

  • GET /photos/{photoId}

  • DELETE /photos/{photoId}

Since you usually want to view or delete specific photos, it makes sense to add an ID for the second two endpoints.

Now, for your users! What HTTP verbs would you need for a user account?  🤔 Additionally, while you don't want users to be able to edit photos once they are already created, it makes sense to be able to edit their user profiles! Also, you want people to be able to see publicly available information about a user without authentication (just like the GitHub API) - so for that one endpoint, you won't need authentication.  What kind of endpoints could you design for that? 

You got this!
You got this! 

Here's what I came up with:

  • POST /users

  • GET /users/{userId}

  • PUT /users/{userId}

  • DELETE /users/{userId}

For creating, editing, and deleting a new user, you would need authentication as well as a specific ID. 😉

Now, for comments!  How could you add those in? If you want users to be able to comment on  another user's photos, you would need to nest a resource within another. This is because a comment needs to be associated with a specific photo. For example, let's say you wanted to create a new comment for a photo with ID.  You could create the endpoint  POST /photos/{photoId}/comments.  Use POST because you're creating something.  Next, working backward: create a comment (/comments) for a specific photo (/{photoId}) among all the other photos (/photos).  

Now, here's a description of three more endpoints you want to create:

  • Get all the comments for a specific photo with ID {photoId}.

  • Get the comment with ID {commentId} for photo with ID {photoId}.

  • Delete the comment with ID {commentId} for photo with ID {photoId}.

You don't want comments to be edited, so don't include an endpoint for that.  Try and write out the endpoints for those three.

You can do it!
You can do it!

Here's what I came up with, including the first one:

Endpoint

Description

POST /photos/{photoId}/comments

Create a new comment for photo with id {photoId}

GET /photos/{photoId}/comments

Get all the comments for a specific photo with id {photoId}

GET /photos/{photoId}/comments/{commentId}

Get the comment with id {commentId} for photo with id {photoId}

DELETE /photos/{photoId}/comments/{commentId}

Delete the comment with id {commentId} for photo with id {photoId}

These would also all require authentication because they should only be changeable by the user who created them. And you could follow the same kind of thought process for all the other resources you'll need.

Let's Recap!

  • When planning, think about what CRUD operations you'll need for which resources.

  • Use resource names and not verbs when naming endpoints.

  • Think about what resources you'll need to contain within other resources.

Example of certificate of achievement
Example of certificate of achievement