Interview Edition: Design a REST API as a Junior Engineer

Step-by-Step Guide on Designing a REST API Along With My Interview Experience

Introduction

Hello! I am writing this purely from my interview experience when I was asked to design an API as a junior level candidate. And no worries, it is not as complicated as you thought and having the fundamental knowledge of an API is the key here. I am here to provide steps which hopefully can make your process at ease, and potentially a template for you if you were ever asked a similar design question.

Table of Content

• Introduction
• Fundamentals You Should Know
• Prompt You’re Given
• Step 1: List All The Potential User Stories/Requirements
• Step 2: Associating actions/HTTP Verbs with User Stories
• Step 3: Request/Response Cycle + Routes + Response Body Content
• Step 4: Other Things Interviewers Might Ask About
• Conclusion

Fundamentals You Should Know

Before we dive into the real stuff, here’s what you should know:

• HTTP Methods (i.e. GET, POST, PUT/PATCH, DELETE)
• Request/Response Cycle 👈 I’d suggest to use this as the backbone when thinking about the correlations between the criteria you’re given and the actions/HTTP methods

[Recommended Resource: Request-Response Cycle I by CodeCademy]

• Routes (The “name” you use to access endpoints)
• Other jargons: endpoints, parameters, arguments, request URL, server’s response
• REST Design Rules (ex: routes should be named with a plural noun and not started with verb, like /posts , not /getPosts )
• HTTP Status Code
• Architecture Difference (ex: GraphQL, REST, SOAP)

Note: In my opinion, as a junior, this is the least you should care about. Just focus on whichever you know best, in this case for the sake of this article would be REST.

• Bonus: Schema/Model

Note: This will help when thinking about the relationships between models [one-to-many? many-to-many?]. However, in my experience, the interviewers would have already stated.

• Additional Bonus: Logic [I had to do some pseudocode]
• Additional Bonus: Error Handling (Understanding the HTTP status code should be good enough as a junior)

With all these in mind, these will help navigate your thought process and don’t forget to think out loud.

Prompt You’re Given

Design an API for a to-do list app.
Note: User is already authenticated.

It seems relatively simple and straightforward, right? When I was reading tips for system design interviews, it is quite common that the prompt is meant to be quite vague and you’re expected to ask questions. And in order for me to understand the prompt better and make sure the interviewers and I are in the same page…

Clarification questions you may have along the way:

• Will there be one list or multiple lists?
• Ans: Just one (i.e. there will be no list_id)
• Do we have to grab any specific user ID? (Thinking for the schema)
• Ans: Since the user is already authenticated, we can disregard user_id.
• As user, can I click on the task and check the details of the task? (Related to the feature itself)
• Ans: Yes, that is indeed an option.

Note: I did not come up with these questions in the beginning. I found it more efficient to ask more effective and smarter questions when I was working on the design, so I can get clarifications in the meantime.

Step 1: List All The Potential User Stories/Requirements

• As user, I can read all the tasks that I create.
• As user, I can create tasks.
• As user, I can update a task.
• As user, I can delete a task.

Step 2: Associating actions/HTTP Verbs with User Stories

Choose the following: GET, POST, PUT, DELETE

• As user, I can read all the tasks that I create.

Since we are listing the tasks only, GET seems like an appropriate HTTP method.

• As user, I can create tasks.

POST is the HTTP method which we will use to create tasks.

• As user, I can update a task.

PUT and PATCH seems like the appropriate HTTP method. Also, it might be a good time to bring up and discuss with the interviewers if they have a preference using PUT vs PATCH, since PUT would update the entire resource and PATCH would only partially update the resource. This also demonstrate your knowledge in HTTP methods.

Note: If interested, feel free to check out this article I wrote more than a year ago: PUT vs PATCH & PUT vs POST 😃

Last but not least,

• As user, I can delete a task.

As obvious as it sounds, DELETE would be our go-to method in this case.

Now that we have identified all the methods, let’s dive into the request/response cycle.

Step 3: Request/Response Cycle + Routes + Body Content

Note: This part is my favorite part of the interview. Not gonna lie, this part is something that I have overseen in the past couple years when building web applications. I finally understood what this means in a deeper level.

After we identify the HTTP methods, it’s time to think about what the client requests and what the server’s response would be like.

At this point, the interviewers gave me some hints by asking what the *request URL* is.

Stating the obvious that we are getting tasks, so tasks would be our endpoint name.

• As user, I can read all the tasks that I create.

// GET
// Request URL: /tasks

After we identify the request URL, what would the server’s response be? A server’s response is consisted of header, body and status code. Usually, we are more interested in seeing the body/data. It might also be a good idea to bring up the HTTP status code as additional bonus point.

Questions that may come up (or hints):

• Which format do we want the server to respond with?
• Ans: Since JSON is more common, we’d receive a JSON format response.
• What kind of stuff can a user see from one specific task?
• Ans: A user can see the date that the task is created, the title of the task and the content of the task.

// GET
// Request URL: /tasks
// Response data:
[
  {
    id: 1,
    title: "task 1",
    content: "this is task 1",
    "date_submitted": "2022-10-18 10:00AM"
  },
  {
    id: 2,
    title: "task 2",
    content: "this is task 2",
    "date_submitted": "2022-10-19 10:00AM"
  },
]
// Response Status Code:
// If successful, 200 OK
// If request resource not found, 404

• Bonus Question: As user, can I click on the task and check the details of the task?
• Ans: Yes.

// GET
// Request URL: /tasks/:id (ex: /tasks/1)
// Response data:
  {
    id: 1,
    title: "task 1",
    content: "this is task 1",
    "date_submitted": "2022-10-18 10:00AM"
  }
// Response Status Code:
// If successful, 200 OK
// If request resource not found, 404 Not Found

• As user, I can create tasks.

// POST
// Request URL: /tasks
// Request body:
{
  id: 3,
  title: "task 3",
  content: "this is task 3",
  "date_submitted": "whichever date and time when you submit - this normally shouldn't be hardcoded on your end."
}
// Response data:
// null

// Response Status Code:
// If successfully created, 201 Created
// If request resource not found, 404 Not Found

• As user, I can update a task.

// PUT
// Request URL: /tasks/:id (ex: /tasks/1)
// Request body:
{
  id: 1,
  title: "NOT task 1",
  content: "this is NOT task 1"
  "date_submitted": "2022-10-18 10:00AM"
}

// Response body: 
// Should return the data that was just updated

// Response status code:
// If successful, 200 OK or 204 No Content or 201 for Created Success
// If task not found, 404

Last but not least,

• As user, I can delete a task.

// DELETE
// Request URL: /tasks/:id (ex: /tasks/1)
// Request body:
{
  id: 1,
  title: "NOT task 1",
  content: "this is NOT task 1"
  "date_submitted": "2022-10-18 10:00AM"
}

// Response Body: null

// Response status code:
// If successful, 200 OK or 204 No Content 
// If task not found, 404 Not Found

Reference from this Stack Overflow post

💡Quick disclaimer on HTTP status code:

When I was doing research on the HTTP status code for different HTTP methods, there are multiple status code that could be returned depending on the operations. The ones I provided above is more of a baseline and there are a lot more to discuss.

There are other things like different parameters (ex: headers). But in my experience, understanding the basics of what kind of data the client is requesting versus what the server returns as response is more important.

Step 4: Other Things Interviewers Might Ask About

The prompt I provided above is relatively simple and your interviewers might add some additional requirements. For instance,

• What happens if there is already a duplicated version of the new task that a user is requesting?

You might be asked to write some logic/pseudocode to reflect that.

• What are the arguments that we are providing to users so they can input and be part of the request?

You might also get asked to write a schema. You might have already seen this if you have studied for system design interviews, or if you have worked with database, like SQL. If it’s difficult for you to brainstorm, think of it by referring back to our request/response cycle.

• What kind of things we want to include in the response body?

Referring back to our tasks example, here’s a possible schema:

task_id         INTEGER PRIMARY_KEY
title           VARCHAR
content         VARCHAR
date_submitted  VARCHAR

Something like that!

Conclusion

Ultimately, it is an open-ended conversation between you and your interviewer. Cliche, I know. BUT!

With the fundamental knowledge you have, not only it helps you navigate around this, but also it demonstrates how much you know to the interviewer. I personally am not kind of person who can come up questions in the first place after hearing the prompt, but as my interviewer and I are navigating the prompt and writing out possible solutions, questions start to come easy and also helps me understand what the interviewers are looking for. [Another factor is that it also depends on the interviewer’s personality/work style too.] As a junior, companies don’t expect as much as they would expect from a senior. So definitely do your best and show them what you got!

Hope this article helps — doesn’t matter if you are prepping for something similar, you already finished yours and curious how other junior candidates approach this question, or you’re just being a Curious George!

For folks who’s curious about the outcome of the interview, I received positive feedback but the role had to be on hold due to hiring freeze in the company.

Please feel free to comment and let me know what else I might be missing in this article!

Last but not least,

Happy Coding and here’s a GIF of Curious George being curious!

Additional Resource

• To understand the request/response of an API, I’d recommend playing around with this swagger page:

Swagger UI

• If you are familiar with Axios, you might be interested in what kind of things Axios’ request config look like:

Request Config