REST Data Formats

Comprehensive guide to data formats used in REST APIs, including JSON, XML, and binary formats

  8 minute read  

Introduction to REST Data Formats

REST architecture doesn’t mandate a specific format for data transmission as long as the representation is based on plaintext. API developers can choose between various formats like JSON, XML, or others based on their specific requirements. Many modern APIs support content negotiation through HTTP headers (using Content-Type and Accept headers), enabling clients to request data in their preferred format.

The choice of data format significantly impacts your API’s usability, performance, parsing complexity, and interoperability. This document explores the most common formats, their pros and cons, and best practices for implementation.

JSON (JavaScript Object Notation)

JSON has become the de facto standard for most modern REST APIs due to its simplicity, readability, and lightweight nature.

Advantages of JSON

  • Compact and Lightweight: Typically requires less bandwidth than XML
  • Native JavaScript Support: Browser-friendly with built-in parsing
  • Human-Readable: Easy to read and write manually
  • Simplicity: Straightforward structure with fewer syntax rules
  • Widespread Support: Native support in nearly all programming languages
  • Performance: Generally faster to parse and serialize than XML

Disadvantages of JSON

  • Limited Validation Options: No built-in schema validation (though solutions like JSON Schema exist)
  • No Comments: Standard JSON doesn’t support comments (though some parsers allow extensions)
  • No Namespace Support: Can lead to naming conflicts
  • Limited Data Types: Fewer built-in data types compared to XML

JSON Example

{
  "user": {
    "id": 1234,
    "name": "Jane Smith",
    "email": "[email protected]",
    "roles": ["admin", "developer"],
    "isActive": true,
    "preferences": {
      "theme": "dark",
      "notifications": true
    },
    "lastLogin": "2025-04-01T14:30:00Z"
  }
}

Using JSON in ASP.NET Core

// Controller returning JSON
[ApiController]
[Route("api/users")]
public class UsersController : ControllerBase
{
    [HttpGet("{id}")]
    public IActionResult GetUser(int id)
    {
        User user = _userService.GetById(id);
        
        if (user == null)
        {
            return NotFound();
        }
        
        return Ok(user); // Automatically serialized to JSON
    }
}

// Deserializing JSON manually
public User DeserializeUser(string json)
{
    User user = JsonSerializer.Deserialize<User>(json);
    return user;
}

XML (Extensible Markup Language)

XML was the dominant format for web services before JSON gained popularity, and it remains important, especially in enterprise environments and legacy systems.

Advantages of XML

  • Strong Validation: Rich schema definition (XSD) and validation capabilities
  • Namespaces: Support for namespaces to avoid naming conflicts
  • Rich Feature Set: Support for comments, processing instructions, and CDATA sections
  • Extensibility: Designed for extensibility through custom schemas and namespaces
  • Mature Tooling: Extensive tool support for transformation (XSLT) and querying (XPath, XQuery)
  • Data Integrity: Strong typing through XML Schema validation

Disadvantages of XML

  • Verbosity: More verbose than JSON, increasing payload size
  • Complexity: More complex to parse and process than JSON
  • Performance Impact: Parsing is typically more resource-intensive
  • Learning Curve: Steeper learning curve for developers
  • Readability: Can be less human-readable with complex structures

XML Example

<user>
  <id>1234</id>
  <name>Jane Smith</name>
  <email>[email protected]</email>
  <roles>
    <role>admin</role>
    <role>developer</role>
  </roles>
  <isActive>true</isActive>
  <preferences>
    <theme>dark</theme>
    <notifications>true</notifications>
  </preferences>
  <lastLogin>2025-04-01T14:30:00Z</lastLogin>
</user>

Using XML in ASP.NET Core

// Controller with XML formatting support
[ApiController]
[Route("api/users")]
[Produces("application/xml", "application/json")]
public class UsersController : ControllerBase
{
    [HttpGet("{id}")]
    public IActionResult GetUser(int id)
    {
        User user = _userService.GetById(id);
        
        if (user == null)
        {
            return NotFound();
        }
        
        // Returns XML or JSON based on Accept header
        return Ok(user);
    }
}

// Deserializing XML manually
public User DeserializeUser(string xml)
{
    XmlSerializer serializer = new XmlSerializer(typeof(User));
    StringReader reader = new StringReader(xml);
    User user = (User)serializer.Deserialize(reader);
    return user;
}

// Setup XML formatting in Program.cs
public static void Main(string[] args)
{
    WebApplicationBuilder builder = WebApplication.CreateBuilder(args);
    
    // Add XML formatters in addition to JSON
    builder.Services.AddControllers()
        .AddXmlSerializerFormatters();
    
    // Rest of configuration...
    
    WebApplication app = builder.Build();
    // Application setup...
    app.Run();
}

Protocol Buffers (Protobuf)

Protocol Buffers, developed by Google, offer a binary serialization format that’s highly efficient but not human-readable without special tools.

Advantages of Protobuf

  • High Performance: Extremely fast serialization/deserialization
  • Compact Size: Significantly smaller payloads than JSON or XML
  • Strong Typing: Schema-based with strong type checking
  • Language Interoperability: Supports many programming languages
  • Backward Compatibility: Built-in versioning support

Disadvantages of Protobuf

  • Not Human-Readable: Binary format requires tools for inspection
  • Schema Required: Requires schema definition (.proto files)
  • Learning Curve: Developers need to learn the protobuf syntax
  • Less Browser-Friendly: Not natively supported in browsers
  • REST Mismatch: Not typically associated with REST (more common in gRPC)

Protobuf Example (Schema)

syntax = "proto3";

message User {
  int32 id = 1;
  string name = 2;
  string email = 3;
  repeated string roles = 4;
  bool is_active = 5;
  
  message Preferences {
    string theme = 1;
    bool notifications = 2;
  }
  
  Preferences preferences = 6;
  string last_login = 7;
}

Using Protobuf in ASP.NET Core

// Add NuGet packages
// dotnet add package Google.Protobuf
// dotnet add package Grpc.Tools
// dotnet add package protobuf-net.AspNetCore

// Program.cs setup
public static void Main(string[] args)
{
    WebApplicationBuilder builder = WebApplication.CreateBuilder(args);
    
    // Add Protobuf support
    builder.Services.AddControllers()
        .AddProtoBufFormatters();
    
    WebApplication app = builder.Build();
    app.Run();
}

// Controller with Protobuf support
[ApiController]
[Route("api/users")]
public class UsersController : ControllerBase
{
    [HttpGet("{id}")]
    [Produces("application/x-protobuf", "application/json")]
    public IActionResult GetUser(int id)
    {
        User user = _userService.GetById(id);
        
        if (user == null)
        {
            return NotFound();
        }
        
        return Ok(user);
    }
}

MessagePack

MessagePack is a binary serialization format that’s similar to JSON but more compact and faster.

Advantages of MessagePack

  • Compact Size: Smaller than JSON (typically 20-50% smaller)
  • High Performance: Fast serialization and deserialization
  • JSON-Compatible Types: Similar data types to JSON
  • Schema Optional: Can be used with or without a schema
  • Multiple Language Support: Libraries available for many languages

Disadvantages of MessagePack

  • Not Human-Readable: Binary format requires tools for inspection
  • Less Mature Ecosystem: Fewer tools compared to JSON or XML
  • Less Browser Support: Not natively supported in browsers
  • Limited Documentation: Less documentation and examples

Using MessagePack in ASP.NET Core

// Add NuGet package
// dotnet add package MessagePack
// dotnet add package MessagePack.AspNetCoreMvcFormatter

// Program.cs setup
public static void Main(string[] args)
{
    WebApplicationBuilder builder = WebApplication.CreateBuilder(args);
    
    // Add MessagePack support
    builder.Services.AddControllers()
        .AddMvcOptions(options =>
        {
            options.OutputFormatters.Add(new MessagePackOutputFormatter(MessagePack.Resolvers.StandardResolver.Instance));
            options.InputFormatters.Add(new MessagePackInputFormatter(MessagePack.Resolvers.StandardResolver.Instance));
        });
    
    WebApplication app = builder.Build();
    app.Run();
}

YAML

YAML (YAML Ain’t Markup Language) is a human-friendly data serialization language, often used for configuration files but rarely for APIs.

Advantages of YAML

  • Human-Readable: Very readable with minimal syntax
  • Comments Support: Allows inclusion of comments
  • Rich Features: Support for references, complex structures
  • Less Verbose: More compact than XML

Disadvantages of YAML for APIs

  • Parsing Complexity: Whitespace sensitivity can lead to errors
  • Performance Issues: Typically slower to parse than JSON
  • Security Concerns: Some parsers have had security vulnerabilities
  • Inconsistent Implementation: Different parsers may handle edge cases differently
  • Limited Browser Support: Not natively supported in browsers

While YAML works well for configuration files, it’s generally not recommended for API responses because:

  1. Its whitespace sensitivity can cause subtle parsing errors
  2. It’s more complex to parse correctly across different languages
  3. It lacks the widespread API tooling support that JSON has
  4. Most API clients expect JSON or XML
  5. Performance characteristics are generally worse than alternatives

If you’re considering YAML for an API, JSON is almost always a better choice due to its widespread support, consistent parsing, and better performance characteristics.

HAL (Hypertext Application Language)

HAL is a format that standardizes the inclusion of hyperlinks in JSON or XML responses, supporting HATEOAS principles.

HAL Example

{
  "_links": {
    "self": { "href": "/users/123" },
    "profile": { "href": "/users/123/profile" },
    "orders": { "href": "/users/123/orders" }
  },
  "id": 123,
  "name": "John Doe",
  "email": "[email protected]"
}

Content Negotiation

Content negotiation is a mechanism defined in HTTP that allows serving different formats of the same resource. It enables clients to specify their preferred response format.

How Content Negotiation Works

  1. The client sends a request with an Accept header specifying preferred formats
  2. The server examines this header and returns the response in the best matching format
  3. The server includes a Content-Type header with the actual response format

Example Accept Headers

Accept: application/json
Accept: application/xml
Accept: application/json, application/xml;q=0.9

Implementing Content Negotiation in ASP.NET Core

// Register formatters in Program.cs
public static void Main(string[] args)
{
    WebApplicationBuilder builder = WebApplication.CreateBuilder(args);
    
    // Add support for JSON and XML
    builder.Services.AddControllers()
        .AddXmlSerializerFormatters()
        .AddJsonOptions(options => 
        {
            options.JsonSerializerOptions.WriteIndented = true;
            options.JsonSerializerOptions.PropertyNamingPolicy = JsonNamingPolicy.CamelCase;
        });
    
    WebApplication app = builder.Build();
    app.Run();
}

// Controller with content negotiation
[ApiController]
[Route("api/users")]
[Produces("application/json", "application/xml")]
public class UsersController : ControllerBase
{
    [HttpGet("{id}")]
    public IActionResult GetUser(int id)
    {
        User user = _userService.GetById(id);
        
        if (user == null)
        {
            return NotFound();
        }
        
        // Will return format based on Accept header
        return Ok(user);
    }
}

Best Practices for REST API Formats

Choosing a Format

  1. Default to JSON for most modern API scenarios
  2. Consider XML if you need strong validation or are in an enterprise environment
  3. Use binary formats like Protocol Buffers only for specific high-performance scenarios
  4. Implement content negotiation to support multiple formats when needed
  5. Avoid YAML for API responses

JSON Best Practices

  1. Use camelCase for property names
  2. Use ISO 8601 for dates (e.g., 2025-04-01T14:30:00Z)
  3. Keep nesting reasonable (avoid deeply nested structures)
  4. Use JSON Schema for validation
  5. Consider pagination for large collections

Content Negotiation Best Practices

  1. Support common formats (at least JSON)
  2. Use proper MIME types (application/json, application/xml, etc.)
  3. Set appropriate defaults when the Accept header is missing
  4. Include format suffixes as an alternative (e.g., /users/123.json)
  5. Handle errors gracefully when requested formats can’t be provided

Performance Considerations

  1. Minimize response size by removing unnecessary fields
  2. Consider compression (gzip, Brotli) for all text formats
  3. Use partial responses with field selection when appropriate
  4. Consider caching headers to improve performance
  5. Monitor payload sizes as your API evolves

Documentation Best Practices

  1. Document all supported formats in your API documentation
  2. Provide examples of each format
  3. Explain how to request specific formats
  4. Document any format-specific limitations
  5. Include schema definitions when applicable

Conclusion

The choice of data format for your REST API has significant implications for usability, performance, and developer experience. JSON has emerged as the dominant format due to its simplicity and widespread support, but alternatives like XML still have important roles in certain scenarios.

By understanding the strengths and weaknesses of each format and implementing proper content negotiation, you can create APIs that are flexible, performant, and meet the needs of your clients. Remember that the best choice depends on your specific requirements, including client needs, performance constraints, and existing system integration considerations.