REST API最佳实践：应采用结构化数据还是键值对传递数据？

Great question—this is a super common dilemma when designing REST APIs, and it’s all about balancing flexibility, maintainability, and developer experience. Let’s break down the best practices here, using your example as a reference.

When to Prefer Structured Objects (Fixed Fields) #

If the data you’re passing is predictable, stable, and has a known set of fields (like your Name, Id, and the Message entries in the example), structured objects are almost always the better choice. Here’s why:

• No messy string comparisons: You can map fields directly to object properties (e.g., countryOfOrigin instead of looping through an array to find a Header matching "Country of origin"). This eliminates bugs from typos (like "Nature of Work" vs. "Nature of work") and makes code cleaner.
• Better type safety & validation: You can use DTO classes, JSON Schema, or API tools to enforce field types and required values. For example, you can ensure Id is a string and CountryOfOrigin isn’t empty.
• Clearer API documentation: Consumers of your API can immediately see what fields are available, instead of guessing what Header values might be supported.
• Easier client integration: Frontend or backend clients don’t have to parse arrays to extract values—they can access fields directly (e.g., response.profile.natureOfWork).

Refactored Example (Structured) #

Instead of a Message array, flatten or nest the fixed fields:

{ 
  "Name" : "Johny English", 
  "Id": "534dsf", 
  "Profile": {
    "CountryOfOrigin": "England",
    "NatureOfWork": "Secret Agent/Spy"
  }
}

When to Use Key-Value Pairs #

Key-value pairs (either as an array or a map) make sense only when your data is dynamic, unstructured, or user-defined. For example:

• If users can add custom attributes to their profiles (e.g., "FavoriteWeapon": "Umbrella", "LicenseNumber": "007") that you can’t predict in advance.
• If you’re building a generic data store API that needs to handle arbitrary fields.

Even then, you can optimize the key-value approach to avoid traversal headaches:

• Use a map instead of an array: Instead of an array of {Header, Value} objects, use a flat object where keys are the headers. This lets you access values directly by key, no loop needed.

  { 
    "Name" : "Johny English", 
    "Id": "534dsf", 
    "Attributes": {
      "Country of origin": "England",
      "Nature of work": "Secret Agent/Spy"
    }
  }
  

• Define allowed keys as enums: If there’s a set of common keys you support, document them as enums. This lets you use enum comparisons instead of raw strings, reducing typos and making code more maintainable.

General Best Practices #

• Design for your consumers: Think about how clients will use your API. If they need to read values frequently, structured objects are friendlier. If they need dynamic extensibility, key-value pairs are the way to go.
• Be consistent: Stick to one style across your API ecosystem unless you have a clear reason to switch. Consistency makes your API easier to learn and use.
• Document everything: If you do use key-value pairs, list common Header values in your API docs, and note whether arbitrary keys are allowed. For structured objects, document each field’s purpose, type, and optional/required status.

内容的提问来源于stack exchange，提问作者Prem