When creating an API, it’s important not to dive in headfirst. You need to think about your API’s architecture, maybe even sketch it out on paper beforehand. What will your API’s role be? What resources will it have? What different levels of access will users be able to get authorization for?
Structuring your API well from the start of the design process will enable you to anticipate errors and have a more solid and better-designed API.
In this chapter, you’re not going to code an API – you’re going to design it. This is an exercise in thinking things through so that you are best prepared to create an API.
Design a Photo-sharing API
For this part, you'll be thinking about how to design an API for a photo-sharing app called InstaPhoto. 📸 You want users to post and share photos with their friends, comment on other people's photos, create hashtags, search photos by location, the whole deal.
Take a minute to write down what you would need to think about when designing an API for InstaPhoto. For example, what resources would you need? What URIs would be understandable to other developers? This exercise is a good chance to review what you've learned in previous parts!
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! You choose! ✨
Design the Endpoints
When designing endpoints, naming is key. You want developers using this to understand what each endpoint is supposed to do. Current naming conventions only include the resource you are trying to update, 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. That gives you:
POST /photo
PUT /photo
GET /photo
Because the verb of the action is already included in the HTTP request, it is not necessary when designing the endpoints.
To help you better understand, the wrong naming for endpoints will look like this:
POST /createPhoto
PUT /updatePhoto
GET /getPhoto
Mocking Out Additional Endpoints
Let's look at the possible endpoints for InstaPhoto.
Again, there's no right or wrong answer here; it depends on your application's needs and how you want to design it.
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 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!
Since you usually want to view or delete specific photos, it makes sense to add an ID for the second two endpoints. This lets the API know which photo it is.
Now for your users! What HTTP verbs would you need for a user account? 🤔 Additionally, while you don't want users 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?
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 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 {photoId}. 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.
All of these endpoints 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.
Think about what resources will require authentication.
You have your list of the CRUD operations you need, your resources and their names, the additional resources, the list of your endpoints, and the endpoints that require authentication. You have a solid foundation, but you could take things even further with search functionality, for example. Carry on to the next chapter, where we’re going to flesh out endpoints using some advanced functionality!
