How to Think Before Writing an API
Coding an API without thinking leads to rework. Here is how to think before you write.
How to Think Before Writing an API
Coding an API without thinking leads to rework. Here is how to think before you write a single line.
Step 1: What Is the User Trying to Do?
Start with the user, not the database. "A user wants to see their matches." This anchors the API design. If you cannot say what the user is trying to do, you do not understand the feature.
Step 2: What Is the Input?
What does the client send? Path params, query params, body. List them. What types? What constraints?
Step 3: What Is the Output?
What does the client need back? A list of matches? A single match? Which fields? Sketch the response shape.
Step 4: What Is the Status Code?
200 for GET, 201 for POST, 204 for DELETE, 400 for validation, 401 for not authenticated, 403 for not authorized, 404 for not found, 409 for conflict, 500 for server error.
Step 5: What Are the Edge Cases?
What if the resource does not exist? What if the user is not authorized? What if the input is invalid? What if there is a duplicate? List each edge case and what the API should do.
Step 6: What Does the Database Need?
Which collections are involved? Which fields? Which relationships? Do you need to populate refs? Do you need an index for the query?
Step 7: What Are the Side Effects?
Does the API send an email? Update a counter? Emit an event? List side effects. Decide which are sync (in the request) and which are async (in a queue).
Step 8: What Are the Permissions?
Who can call this API? Any authenticated user? Only the owner? Only admins? Write the auth and authorization rules.
Step 9: What Is the Validation?
What fields are required? What types? What constraints (min, max, enum)? Write the Zod schema.
Step 10: Write the LLD
Put it all in a short doc: endpoint, input, output, status codes, edge cases, database needs, side effects, permissions, validation. Then code from the doc.
The Takeaway
Think before writing an API: what is the user trying to do, what is the input, what is the output, what is the status code, what are the edge cases, what does the database need, what are the side effects, what are the permissions, what is the validation, and write the LLD. Coding from a doc prevents rework.
Start with what the user is trying to do. Then define input, output, status codes, edge cases, database needs, side effects, permissions, and validation. Write a short LLD doc. Then code from the doc.
Because the API serves the user. If you cannot say what the user is trying to do, you do not understand the feature. Starting with the user anchors every other decision (input, output, edge cases).
Resource does not exist (404), user not authenticated (401), user not authorized (403), input invalid (400), duplicate (409), and server error (500). For each, decide what the API should do.
Emails, counter updates, event emissions, notifications. For each, decide if it is sync (in the request) or async (in a queue). Sync side effects slow the request; async ones do not.
Coding from a doc prevents rework. The doc forces you to think through input, output, edge cases, database needs, side effects, permissions, and validation. A few hours of LLD saves days of rewriting.
Ready to master Node.js completely?
Want to upskill yourself, crack your next interview, and get your dream job? Join our comprehensive course to dive deeper with high-quality video tutorials, solve interview questions, and a premium community.
Master Node.js
Want to upskill yourself, crack your next interview, and get your dream job? Join our comprehensive course.