Designing Request Bodies: Validation and Naming Conventions

Previously in this course, we discussed JSON as the Standard Exchange Format for REST APIs, establishing how our services communicate. Now that we know how to send data, we must address the most important rule of backend development: never trust the client.

In this lesson, we will define how to structure incoming data for our Task Manager project, implement strict validation, and establish a naming convention that keeps our API predictable.

The Anatomy of a Request Body

When a client sends a POST or PUT request, they provide a Request Body—a JSON payload containing the data the server needs to process. Designing this body isn't just about throwing fields into an object; it’s about defining a contract. If your API expects a title, but the client sends task_name, your internal logic will break.

To keep our API maintainable, we must enforce two pillars: consistency and validity.

1. Consistent Field Naming Conventions

In REST APIs, inconsistency is the enemy of developer experience. If one endpoint uses camelCase and another uses snake_case, your API consumers will constantly make errors.

Standardize early:

• Use camelCase for JSON keys: It is the industry standard for JSON APIs (e.g., taskTitle, isCompleted, dueDate).
• Be explicit: Avoid abbreviations. assignedUserId is always better than uid or asgnTo.
• Keep it flat where possible: Deeply nested structures are harder to validate and harder to use on the client side.

2. Validating JSON Request Bodies

Validation is the process of ensuring the incoming data matches your defined Defining the Data Schema for your Task Manager API. If the client sends a string where you expect an integer, or misses a required field entirely, you must reject the request immediately.

Never process raw input. Instead, use a validation layer to ensure:

• Type Safety: Are the types correct?
• Presence: Are required fields present?
• Constraints: Does the title have a minimum length? Is the dueDate in the future?

Worked Example: Validating a Task Creation

Let’s define a schema for creating a task in our Task Manager. We expect a JSON object with a title (required, string) and a priority (optional, integer 1-3).

JSON
// POST /tasks
{
  "title": "Finish API documentation",
  "priority": 2
}

If a client sends invalid data, we must return a 400 Bad Request. Implementing Request Validation in API Gateway: A Practical Guide can save you from writing custom code for every route, but even if you handle it in your controller, the logic remains the same:

JAVASCRIPT
function validateTask(data) {
  const errors = [];

  if (!data.title || typeof data.title !== CE9178">'string') {
    errors.push("Field CE9178">'title' is required and must be a string.");
  }
  
  if (data.priority && (data.priority < 1 || data.priority > 3)) {
    errors.push("Field CE9178">'priority' must be between 1 and 3.");
  }

  return {
    isValid: errors.length === 0,
    errors
  };
}

By checking this before hitting your database logic, you prevent malformed data from ever entering your system, avoiding potential Mass Assignment Prevention: Securing JSON-to-ORM Mapping issues.

Hands-on Exercise

1. Open your tasks route handler.
2. Create a "validation middleware" function that accepts the req.body.
3. Ensure the title field is at least 3 characters long.
4. If the validation fails, respond with a 400 Bad Request and a JSON object containing the list of error messages.

Common Pitfalls

• Trusting the Client: Never assume the client followed the documentation. Always re-validate on the server.
• Over-Validation: Don't enforce business rules that might change (like "no tasks on weekends") in your primary validation layer. Keep the schema validation focused on structure, and domain validation focused on business logic.
• Silent Failures: If a client sends an extra field that your database doesn't need, don't just ignore it—explicitly strip it out or reject the request to ensure your API contract remains strict.

FAQ

Q: Should I return the validation error for every field at once? A: Yes. It is much better to return a list of all validation errors so the client can fix them in one go, rather than failing on the first error and forcing multiple round trips.

Q: Is it okay to use snake_case if my database uses it? A: Your API's naming convention should be independent of your database schema. Use camelCase for your JSON API regardless of your database’s underlying format.

Recap

Designing a request body is your first line of defense. By enforcing consistent camelCase naming conventions and strictly validating incoming JSON against your schema, you create an API that is predictable, secure, and easy for other developers to integrate with.

Up next: Standardizing Response Envelopes