OData

Understanding OData as an extension to REST for building queryable APIs in .NET

  16 minute read  

Introduction to OData

OData (Open Data Protocol) is an ISO/IEC approved, OASIS standard that defines a set of best practices for building and consuming RESTful APIs. Created by Microsoft in 2007, OData extends standard REST principles by adding a uniform way to query data, represent complex data structures, and implement standardized CRUD operations.

Rather than being an alternative to REST, OData can be seen as a standardized implementation of REST principles, offering a more structured and consistent approach to API design.

Key Features of OData

  • Standardized URL Query Syntax: Filtering, sorting, paging, and selecting specific fields
  • Complex Data Models: Support for relationships, inheritance, and complex types
  • CRUD Operations: Standardized approach to Create, Read, Update, and Delete operations
  • Metadata: Self-describing services with standardized metadata documents
  • Protocol Negotiation: Support for different formats (JSON, XML) and protocol versions
  • Batching: Ability to combine multiple operations in a single HTTP request
  • Functionality Extensions: Functions and actions for custom operations
  • Strong Typing: Strict schema definition for data exchange
  • Ecosystem Support: Extensive tooling and client library support

OData and REST Relationship

OData is built on top of REST principles, but provides additional standardization:

FeatureStandard RESTOData
Resource AddressingCustom URL conventionsStandardized URL patterns
Query CapabilitiesCustom query parametersStandardized query options ($filter, $select, etc.)
Response FormatTypically JSON, format variesStrictly defined JSON/XML formats
MetadataOften described with OpenAPIBuilt-in metadata document (/$metadata)
CRUD OperationsHTTP methods on resourcesHTTP methods plus standardized request/response formats
RelationshipsCustom representationsStandardized navigation properties
BatchingNot standardizedBuilt-in $batch functionality
Client Code GenerationRequires OpenAPI or custom solutionBuilt-in metadata enables automatic code generation

When to Use OData

OData is particularly well-suited for:

  1. Data-Centric Applications: When your API primarily exposes a data model
  2. Ad-Hoc Querying: When clients need flexibility in how they query data
  3. Complex Data Models: When you have relationships and hierarchies
  4. Standardized Tooling: When you want to leverage OData client libraries
  5. Enterprise Environments: Where standards compliance is important
  6. Reducing API Endpoints: When you want fewer endpoints with more query capabilities
  7. Self-Documenting Services: When you want built-in discoverability

Getting Started with OData in ASP.NET Core

ASP.NET Core provides excellent support for building OData services. Let’s walk through the steps to create an OData API.

Setting Up the Project

First, install the required NuGet packages:

dotnet add package Microsoft.AspNetCore.OData
dotnet add package Microsoft.EntityFrameworkCore
dotnet add package Microsoft.EntityFrameworkCore.InMemory

Define Your Data Model

Create a data model for your OData service:

using System;
using System.Collections.Generic;

namespace ODataDemo.Models
{
    public class Book
    {
        public int Id { get; set; }
        public string Title { get; set; }
        public string Author { get; set; }
        public int PublicationYear { get; set; }
        public string ISBN { get; set; }
        public decimal Price { get; set; }
        public int CategoryId { get; set; }
        public Category Category { get; set; }
        public ICollection<Review> Reviews { get; set; }
    }

    public class Category
    {
        public int Id { get; set; }
        public string Name { get; set; }
        public string Description { get; set; }
        public ICollection<Book> Books { get; set; }
    }

    public class Review
    {
        public int Id { get; set; }
        public int BookId { get; set; }
        public string Reviewer { get; set; }
        public int Rating { get; set; }
        public string Comment { get; set; }
        public DateTime ReviewDate { get; set; }
        public Book Book { get; set; }
    }
}

Create a DbContext

Set up a DbContext for Entity Framework:

using Microsoft.EntityFrameworkCore;
using ODataDemo.Models;

namespace ODataDemo.Data
{
    public class BookstoreContext : DbContext
    {
        public BookstoreContext(DbContextOptions<BookstoreContext> options)
            : base(options)
        {
        }

        public DbSet<Book> Books { get; set; }
        public DbSet<Category> Categories { get; set; }
        public DbSet<Review> Reviews { get; set; }

        protected override void OnModelCreating(ModelBuilder modelBuilder)
        {
            // Configure Book entity
            modelBuilder.Entity<Book>()
                .HasKey(b => b.Id);

            modelBuilder.Entity<Book>()
                .HasOne(b => b.Category)
                .WithMany(c => c.Books)
                .HasForeignKey(b => b.CategoryId);

            modelBuilder.Entity<Book>()
                .HasMany(b => b.Reviews)
                .WithOne(r => r.Book)
                .HasForeignKey(r => r.BookId);

            // Configure Category entity
            modelBuilder.Entity<Category>()
                .HasKey(c => c.Id);

            // Configure Review entity
            modelBuilder.Entity<Review>()
                .HasKey(r => r.Id);

            // Seed data
            modelBuilder.Entity<Category>().HasData(
                new Category { Id = 1, Name = "Fiction", Description = "Fictional literature" },
                new Category { Id = 2, Name = "Non-fiction", Description = "Factual content" },
                new Category { Id = 3, Name = "Technical", Description = "Technical documentation and guides" }
            );

            modelBuilder.Entity<Book>().HasData(
                new Book { Id = 1, Title = "The Great Gatsby", Author = "F. Scott Fitzgerald", PublicationYear = 1925, ISBN = "9780743273565", Price = 12.99m, CategoryId = 1 },
                new Book { Id = 2, Title = "Clean Code", Author = "Robert C. Martin", PublicationYear = 2008, ISBN = "9780132350884", Price = 37.99m, CategoryId = 3 },
                new Book { Id = 3, Title = "A Brief History of Time", Author = "Stephen Hawking", PublicationYear = 1988, ISBN = "9780553380163", Price = 14.99m, CategoryId = 2 }
            );

            modelBuilder.Entity<Review>().HasData(
                new Review { Id = 1, BookId = 1, Reviewer = "John Smith", Rating = 5, Comment = "A classic masterpiece!", ReviewDate = new DateTime(2023, 1, 15) },
                new Review { Id = 2, BookId = 1, Reviewer = "Jane Doe", Rating = 4, Comment = "Beautifully written.", ReviewDate = new DateTime(2023, 3, 22) },
                new Review { Id = 3, BookId = 2, Reviewer = "Bob Johnson", Rating = 5, Comment = "Changed how I write code.", ReviewDate = new DateTime(2022, 11, 8) }
            );
        }
    }
}

Configure OData in Program.cs

Configure OData in your ASP.NET Core application:

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.OData;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.OData.Edm;
using Microsoft.OData.ModelBuilder;
using ODataDemo.Data;
using ODataDemo.Models;

WebApplicationBuilder builder = WebApplication.CreateBuilder(args);

// Add services to the container
builder.Services.AddDbContext<BookstoreContext>(options =>
    options.UseInMemoryDatabase("BookstoreDb"));

// Add Controllers with OData support
builder.Services.AddControllers()
    .AddOData(options => options
        .Select()  // Enable $select
        .Filter()  // Enable $filter
        .Count()   // Enable $count
        .OrderBy() // Enable $orderby
        .Expand()  // Enable $expand
        .SetMaxTop(100) // Limit $top
        .AddRouteComponents("odata", GetEdmModel())); // Configure EDM model

WebApplication app = builder.Build();

// Configure the HTTP request pipeline
app.UseHttpsRedirection();
app.UseRouting();
app.UseAuthorization();

app.MapControllers();

app.Run();

// Define your EDM model
IEdmModel GetEdmModel()
{
    ODataConventionModelBuilder modelBuilder = new ODataConventionModelBuilder();
    
    // Register entity sets
    modelBuilder.EntitySet<Book>("Books");
    modelBuilder.EntitySet<Category>("Categories");
    modelBuilder.EntitySet<Review>("Reviews");
    
    // Create a function to get top-rated books
    modelBuilder.EntityType<Book>()
        .Collection
        .Function("TopRated")
        .ReturnsCollectionFromEntitySet<Book>("Books")
        .Parameter<int>("minRating");
    
    // Create an action to discount a book
    modelBuilder.EntityType<Book>()
        .Action("ApplyDiscount")
        .Parameter<decimal>("discountPercentage");
    
    return modelBuilder.GetEdmModel();
}

Create OData Controllers

Now create the OData controllers to handle requests:

using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.OData.Deltas;
using Microsoft.AspNetCore.OData.Formatter;
using Microsoft.AspNetCore.OData.Query;
using Microsoft.AspNetCore.OData.Results;
using Microsoft.AspNetCore.OData.Routing.Controllers;
using Microsoft.EntityFrameworkCore;
using ODataDemo.Data;
using ODataDemo.Models;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;

namespace ODataDemo.Controllers
{
    public class BooksController : ODataController
    {
        private readonly BookstoreContext _context;

        public BooksController(BookstoreContext context)
        {
            _context = context;
        }

        // GET: /odata/Books
        [EnableQuery]
        public IActionResult Get()
        {
            return Ok(_context.Books);
        }

        // GET: /odata/Books(1)
        [EnableQuery]
        public async Task<IActionResult> Get([FromODataUri] int key)
        {
            Book book = await _context.Books.FindAsync(key);
            
            if (book == null)
            {
                return NotFound();
            }
            
            return Ok(book);
        }

        // POST: /odata/Books
        public async Task<IActionResult> Post([FromBody] Book book)
        {
            if (!ModelState.IsValid)
            {
                return BadRequest(ModelState);
            }
            
            _context.Books.Add(book);
            await _context.SaveChangesAsync();
            
            return Created(book);
        }

        // PUT: /odata/Books(1)
        public async Task<IActionResult> Put([FromODataUri] int key, [FromBody] Book book)
        {
            if (!ModelState.IsValid)
            {
                return BadRequest(ModelState);
            }
            
            if (key != book.Id)
            {
                return BadRequest();
            }
            
            _context.Entry(book).State = EntityState.Modified;
            
            try
            {
                await _context.SaveChangesAsync();
            }
            catch (DbUpdateConcurrencyException)
            {
                if (!await _context.Books.AnyAsync(b => b.Id == key))
                {
                    return NotFound();
                }
                else
                {
                    throw;
                }
            }
            
            return Updated(book);
        }

        // PATCH: /odata/Books(1)
        public async Task<IActionResult> Patch([FromODataUri] int key, [FromBody] Delta<Book> delta)
        {
            if (!ModelState.IsValid)
            {
                return BadRequest(ModelState);
            }
            
            Book book = await _context.Books.FindAsync(key);
            
            if (book == null)
            {
                return NotFound();
            }
            
            delta.Patch(book);
            
            try
            {
                await _context.SaveChangesAsync();
            }
            catch (DbUpdateConcurrencyException)
            {
                if (!await _context.Books.AnyAsync(b => b.Id == key))
                {
                    return NotFound();
                }
                else
                {
                    throw;
                }
            }
            
            return Updated(book);
        }

        // DELETE: /odata/Books(1)
        public async Task<IActionResult> Delete([FromODataUri] int key)
        {
            Book book = await _context.Books.FindAsync(key);
            
            if (book == null)
            {
                return NotFound();
            }
            
            _context.Books.Remove(book);
            await _context.SaveChangesAsync();
            
            return NoContent();
        }

        // GET: /odata/Books(1)/Category
        [EnableQuery]
        public SingleResult<Category> GetCategory([FromODataUri] int key)
        {
            IQueryable<Category> result = _context.Books
                .Where(b => b.Id == key)
                .Select(b => b.Category);
                
            return SingleResult.Create(result);
        }

        // GET: /odata/Books(1)/Reviews
        [EnableQuery]
        public IQueryable<Review> GetReviews([FromODataUri] int key)
        {
            return _context.Books
                .Where(b => b.Id == key)
                .SelectMany(b => b.Reviews);
        }

        // Function: /odata/Books/TopRated(minRating=4)
        [HttpGet]
        public IActionResult TopRated([FromODataUri] int minRating)
        {
            // Find books with average rating >= minRating
            IQueryable<Book> topRatedBooks = _context.Books
                .Where(b => b.Reviews.Any())
                .Where(b => b.Reviews.Average(r => r.Rating) >= minRating);
                
            return Ok(topRatedBooks);
        }

        // Action: /odata/Books(1)/ApplyDiscount
        [HttpPost]
        public async Task<IActionResult> ApplyDiscount([FromODataUri] int key, ODataActionParameters parameters)
        {
            if (!ModelState.IsValid)
            {
                return BadRequest(ModelState);
            }
            
            // Extract discount percentage from parameters
            if (!parameters.TryGetValue("discountPercentage", out object discountObj) || !(discountObj is decimal discountPercentage))
            {
                return BadRequest("Missing or invalid discount percentage");
            }
            
            Book book = await _context.Books.FindAsync(key);
            
            if (book == null)
            {
                return NotFound();
            }
            
            // Apply discount
            book.Price = book.Price * (1 - discountPercentage / 100);
            
            await _context.SaveChangesAsync();
            
            return Ok(book);
        }
    }
}

Create controllers for other entities as well:

using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.OData.Deltas;
using Microsoft.AspNetCore.OData.Formatter;
using Microsoft.AspNetCore.OData.Query;
using Microsoft.AspNetCore.OData.Results;
using Microsoft.AspNetCore.OData.Routing.Controllers;
using Microsoft.EntityFrameworkCore;
using ODataDemo.Data;
using ODataDemo.Models;
using System.Linq;
using System.Threading.Tasks;

namespace ODataDemo.Controllers
{
    public class CategoriesController : ODataController
    {
        private readonly BookstoreContext _context;

        public CategoriesController(BookstoreContext context)
        {
            _context = context;
        }

        // GET: /odata/Categories
        [EnableQuery]
        public IActionResult Get()
        {
            return Ok(_context.Categories);
        }

        // GET: /odata/Categories(1)
        [EnableQuery]
        public async Task<IActionResult> Get([FromODataUri] int key)
        {
            Category category = await _context.Categories.FindAsync(key);
            
            if (category == null)
            {
                return NotFound();
            }
            
            return Ok(category);
        }

        // GET: /odata/Categories(1)/Books
        [EnableQuery]
        public IQueryable<Book> GetBooks([FromODataUri] int key)
        {
            return _context.Categories
                .Where(c => c.Id == key)
                .SelectMany(c => c.Books);
        }

        // Other CRUD operations omitted for brevity
    }

    public class ReviewsController : ODataController
    {
        private readonly BookstoreContext _context;

        public ReviewsController(BookstoreContext context)
        {
            _context = context;
        }

        // GET: /odata/Reviews
        [EnableQuery]
        public IActionResult Get()
        {
            return Ok(_context.Reviews);
        }

        // GET: /odata/Reviews(1)
        [EnableQuery]
        public async Task<IActionResult> Get([FromODataUri] int key)
        {
            Review review = await _context.Reviews.FindAsync(key);
            
            if (review == null)
            {
                return NotFound();
            }
            
            return Ok(review);
        }

        // Other CRUD operations omitted for brevity
    }
}

OData Query Capabilities

One of OData’s most powerful features is its standardized query language. Here are the key query options:

$filter - Filtering Results

Filter results based on field values:

// Books published after 2000
GET /odata/Books?$filter=PublicationYear gt 2000

// Books by a specific author
GET /odata/Books?$filter=Author eq 'Stephen Hawking'

// Books with price less than 20 and published after 2000
GET /odata/Books?$filter=Price lt 20 and PublicationYear gt 2000

// Books with "Code" in the title
GET /odata/Books?$filter=contains(Title, 'Code')

// Books in category with ID 3
GET /odata/Books?$filter=CategoryId eq 3

$orderby - Sorting Results

Order results by one or more properties:

// Order books by price (ascending)
GET /odata/Books?$orderby=Price

// Order books by price (descending)
GET /odata/Books?$orderby=Price desc

// Order by multiple fields
GET /odata/Books?$orderby=CategoryId,PublicationYear desc

$top and $skip - Pagination

Limit the number of results and skip records:

// Get first 10 books
GET /odata/Books?$top=10

// Skip the first 10 books and get the next 10
GET /odata/Books?$skip=10&$top=10

$select - Field Selection

Choose which fields to include in the response:

// Return only the title and author
GET /odata/Books?$select=Title,Author,Price

$expand - Including Related Entities

Include related entities in the response:

// Include the category with each book
GET /odata/Books?$expand=Category

// Include reviews with each book
GET /odata/Books?$expand=Reviews

// Include both category and reviews
GET /odata/Books?$expand=Category,Reviews

// Select specific fields from expanded entities
GET /odata/Books?$expand=Reviews($select=Rating,Comment)

// Filter expanded entities
GET /odata/Books?$expand=Reviews($filter=Rating ge 4)

$count - Counting Results

Get the total count of records that match a query:

// Get total number of books
GET /odata/Books?$count=true

// Get total count with filtering
GET /odata/Books?$filter=PublicationYear gt 2000&$count=true

Combining Query Options

You can combine multiple query options in a single request:

// Complex query combining multiple options
GET /odata/Books?$filter=Price lt 30&$orderby=PublicationYear desc&$top=5&$skip=5&$select=Title,Author,Price&$expand=Category($select=Name)&$count=true

OData Client Consumption in .NET

Installing Client Packages

To consume OData services in a .NET client, install the necessary NuGet packages:

dotnet add package Microsoft.OData.Client

Generated Client Code

OData provides tools to generate client-side code from service metadata. You can use the OData Connected Service extension in Visual Studio or the OData CLI.

Once you have the generated code, you can use it to query the service:

using System;
using System.Linq;
using ODataDemo.Client;

namespace ODataClientApp
{
    class Program
    {
        static void Main()
        {
            // Create the OData service context
            string serviceRoot = "https://localhost:5001/odata";
            BookstoreContext context = new BookstoreContext(new Uri(serviceRoot));
            
            Console.WriteLine("Querying books...");
            
            // Query books published after 2000
            System.Collections.Generic.IEnumerable<Book> recentBooks = context.Books
                .Where(b => b.PublicationYear > 2000)
                .OrderBy(b => b.Title)
                .Execute();
                
            foreach (Book book in recentBooks)
            {
                Console.WriteLine($"Title: {book.Title}, Author: {book.Author}, Year: {book.PublicationYear}");
            }
            
            // Get a specific book with its category and reviews
            Book bookWithDetails = context.Books
                .Where(b => b.Id == 2)
                .Expand(b => b.Category)
                .Expand(b => b.Reviews)
                .FirstOrDefault();
                
            if (bookWithDetails != null)
            {
                Console.WriteLine($"\nDetails for: {bookWithDetails.Title}");
                Console.WriteLine($"Category: {bookWithDetails.Category.Name}");
                Console.WriteLine("Reviews:");
                
                foreach (Review review in bookWithDetails.Reviews)
                {
                    Console.WriteLine($"- {review.Rating}/5: {review.Comment}");
                }
            }
            
            // Create a new book
            Book newBook = new Book
            {
                Title = "New Programming Paradigms",
                Author = "Jane Programmer",
                PublicationYear = 2023,
                ISBN = "9781234567890",
                Price = 29.99m,
                CategoryId = 3
            };
            
            context.AddToBooks(newBook);
            context.SaveChanges();
            
            Console.WriteLine($"\nAdded new book with ID: {newBook.Id}");
        }
    }
}

Manual HTTP Requests

You can also make manual HTTP requests to OData endpoints:

using System;
using System.Net.Http;
using System.Text.Json;
using System.Threading.Tasks;

namespace ODataManualClient
{
    class Program
    {
        static async Task Main()
        {
            HttpClient httpClient = new HttpClient();
            httpClient.BaseAddress = new Uri("https://localhost:5001/odata/");
            
            try
            {
                // Get books with filtering and select
                string requestUri = "Books?$filter=Price lt 20&$select=Id,Title,Author,Price&$orderby=Title";
                HttpResponseMessage response = await httpClient.GetAsync(requestUri);
                response.EnsureSuccessStatusCode();
                
                string content = await response.Content.ReadAsStringAsync();
                JsonDocument document = JsonDocument.Parse(content);
                JsonElement root = document.RootElement;
                
                Console.WriteLine("Books under $20:");
                foreach (JsonElement book in root.GetProperty("value").EnumerateArray())
                {
                    string title = book.GetProperty("Title").GetString();
                    string author = book.GetProperty("Author").GetString();
                    decimal price = book.GetProperty("Price").GetDecimal();
                    
                    Console.WriteLine($"Title: {title}, Author: {author}, Price: ${price}");
                }
            }
            catch (HttpRequestException ex)
            {
                Console.WriteLine($"Error accessing OData service: {ex.Message}");
            }
        }
    }
}

Advanced OData Features

Batch Operations

OData supports batching multiple operations in a single HTTP request:

// Client-side batch processing
using System;
using System.Collections.Generic;
using Microsoft.OData.Client;
using ODataDemo.Client;

namespace ODataBatchClient
{
    class Program
    {
        static void Main()
        {
            string serviceRoot = "https://localhost:5001/odata";
            BookstoreContext context = new BookstoreContext(new Uri(serviceRoot));
            
            // Start a batch operation
            context.BeginBatch();
            
            try
            {
                // Create a new category
                Category category = new Category
                {
                    Name = "Science Fiction",
                    Description = "Books about futuristic concepts"
                };
                
                context.AddToCategories(category);
                
                // Create multiple books in the same batch
                List<Book> newBooks = new List<Book>
                {
                    new Book
                    {
                        Title = "Dune",
                        Author = "Frank Herbert",
                        PublicationYear = 1965,
                        ISBN = "9780441172719",
                        Price = 11.99m,
                        CategoryId = 1
                    },
                    new Book
                    {
                        Title = "Neuromancer",
                        Author = "William Gibson",
                        PublicationYear = 1984,
                        ISBN = "9780441569595",
                        Price = 14.99m,
                        CategoryId = 1
                    }
                };
                
                foreach (Book book in newBooks)
                {
                    context.AddToBooks(book);
                }
                
                // Update an existing book in the same batch
                Book bookToUpdate = context.Books.ByKey(1).GetValue();
                bookToUpdate.Price = 10.99m;
                context.UpdateObject(bookToUpdate);
                
                // Execute all operations as a batch
                context.SaveChanges(SaveChangesOptions.BatchWithSingleChangeset);
                
                Console.WriteLine("Batch operations completed successfully.");
            }
            catch (Exception ex)
            {
                Console.WriteLine($"Error in batch operations: {ex.Message}");
            }
        }
    }
}

Functions and Actions

OData differentiates between functions (non-state-changing operations) and actions (state-changing operations):

// Server-side function implementation
[HttpGet]
public IActionResult GetTopSellingBooks([FromODataUri] int count)
{
    IQueryable<Book> topSellingBooks = _context.Books
        .OrderByDescending(b => b.Sales)
        .Take(count);
        
    return Ok(topSellingBooks);
}

// Server-side action implementation
[HttpPost]
public async Task<IActionResult> PublishBook([FromODataUri] int key)
{
    Book book = await _context.Books.FindAsync(key);
    
    if (book == null)
    {
        return NotFound();
    }
    
    book.IsPublished = true;
    book.PublishDate = DateTime.Now;
    
    await _context.SaveChangesAsync();
    
    return Ok(book);
}

// Client-side function call
Uri functionUri = new Uri($"{serviceRoot}/Books/Default.TopRated(minRating=4)");
DataServiceQuery<Book> topRatedBooks = context.Execute<Book>(functionUri);

foreach (Book book in topRatedBooks)
{
    Console.WriteLine($"{book.Title} - Highly rated!");
}

// Client-side action call
Uri actionUri = new Uri($"{serviceRoot}/Books(2)/Default.ApplyDiscount");
OperationParameter parameter = new OperationParameter("discountPercentage", 15);
Book discountedBook = context.Execute<Book>(actionUri, "POST", parameter).Single();

Console.WriteLine($"{discountedBook.Title} discounted to ${discountedBook.Price}");

Open Types

OData supports open types with dynamic properties:

// Define an open type
public class DynamicEntity
{
    public int Id { get; set; }
    public string Name { get; set; }
    
    [OpenPropertyType]
    public Dictionary<string, object> Properties { get; set; } = new Dictionary<string, object>();
}

// Configure in the EDM model
modelBuilder.EntityType<DynamicEntity>().HasKey(e => e.Id);
modelBuilder.EntitySet<DynamicEntity>("DynamicEntities");

// Client using an open type
DynamicEntity entity = new DynamicEntity
{
    Name = "Dynamic Data"
};

entity.Properties["Location"] = "New York";
entity.Properties["IsActive"] = true;
entity.Properties["Score"] = 95.5;

context.AddToDynamicEntities(entity);
context.SaveChanges();

Best Practices for OData APIs

1. Control Query Complexity

Limit the complexity of queries to prevent performance issues:

// Configure query options with limitations
services.AddControllers()
    .AddOData(options => options
        .Select()
        .Filter()  
        .OrderBy()
        .SetMaxTop(100)  // Limit maximum records
        .Count()
        .Expand()
        .AddRouteComponents("odata", GetEdmModel()));

2. Implement Server-Side Paging

Always use server-side paging for large result sets:

[EnableQuery(PageSize = 10, MaxExpansionDepth = 3)]
public IActionResult Get()
{
    return Ok(_context.Books);
}

3. Use ETags for Concurrency Control

Implement optimistic concurrency using ETags:

// Configure entity for concurrency
modelBuilder.Entity<Book>()
    .Property(b => b.RowVersion)
    .IsRowVersion();
    
// In your controller
[EnableQuery]
public async Task<IActionResult> Put([FromODataUri] int key, [FromBody] Book book)
{
    // Check ETag
    if (!Request.Headers.TryGetValue("If-Match", out Microsoft.Extensions.Primitives.StringValues etag))
    {
        return BadRequest("ETag header is required for updates");
    }
    
    // Normal update logic...
}

4. Secure Your OData Endpoints

Apply proper authorization to controllers and queries:

[Authorize]
[EnableQuery(AllowedQueryOptions = AllowedQueryOptions.Select | AllowedQueryOptions.Filter)]
public IActionResult Get()
{
    // Only return books the current user has access to
    string userId = User.FindFirst(ClaimTypes.NameIdentifier)?.Value;
    return Ok(_context.Books.Where(b => b.OwnerId == userId));
}

5. Use Custom Serialization When Needed

Configure OData serialization for specific needs:

services.AddControllers(options =>
{
    foreach (ODataOutputFormatter outputFormatter in options.OutputFormatters.OfType<ODataOutputFormatter>().Where(x => x.SupportedMediaTypes.Count == 0))
    {
        outputFormatter.SupportedMediaTypes.Add("application/json;odata.metadata=minimal");
    }
});

6. Document Your OData API

Document your API for consumers:

// Add Swagger support for OData
services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "OData Bookstore API", Version = "v1" });
});

// Configure OData-specific Swagger options
services.AddOdataSwaggerSupport();

7. Version Your APIs

Implement versioning for OData services:

// Add API versioning
services.AddApiVersioning(options =>
{
    options.ReportApiVersions = true;
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.AssumeDefaultVersionWhenUnspecified = true;
});

services.AddODataApiExplorer(options =>
{
    options.GroupNameFormat = "'v'VVV";
    options.SubstituteApiVersionInUrl = true;
});

// Configure versioned models
IEdmModel GetEdmModelV1()
{
    // V1 model definition
}

IEdmModel GetEdmModelV2()
{
    // V2 model definition
}

// Register versioned models
app.UseMvc(routeBuilder =>
{
    routeBuilder.MapVersionedODataRoutes("odata", "api/v{version:apiVersion}", 
        new Dictionary<ApiVersion, IEdmModel>
        {
            { new ApiVersion(1, 0), GetEdmModelV1() },
            { new ApiVersion(2, 0), GetEdmModelV2() }
        });
});

OData vs. GraphQL

OData and GraphQL are both query languages for APIs, but they differ in several key aspects:

FeatureODataGraphQL
Query LanguageURL-based parametersRequest body schema
Result FormatServer-controlled structureClient-specified structure
Multiple Resources$expand parameterSingle query for multiple resources
ProtocolBuilt on REST/HTTPTransport agnostic (typically HTTP)
Query ComplexityLimited by allowed optionsLimited by query complexity analysis
StandardizationOASIS standardGraphQL Foundation specification
Learning CurveModerateSteep
EcosystemMicrosoft-focusedWider adoption
SchemaXML metadata documentGraphQL schema language
Discovery$metadata endpointIntrospection queries

OData vs. Other REST Approaches

FeatureODataPlain RESTgRPCSOAP
StandardizationHighVariesHighHigh
Query FlexibilityHighLowLowLow
PerformanceGoodExcellentExcellentPoor
ComplexityModerateLowModerateHigh
ToolingExtensiveVariesGoodExtensive
DiscoverabilityExcellentVariesLimitedGood
Browser SupportFullFullLimitedLimited
Learning CurveModerateLowModerateSteep

Conclusion

OData provides a standardized approach to building and consuming RESTful APIs with powerful querying capabilities. It excels in data-centric scenarios where clients need flexibility in how they access and manipulate data. By providing a consistent, well-defined protocol for data access, OData reduces the need for custom API endpoints and allows clients to query exactly what they need.

The trade-off for this flexibility is increased complexity compared to simpler REST approaches. OData services require more configuration and have a steeper learning curve for both API providers and consumers. However, the rich ecosystem of tools and libraries can offset this complexity for teams that want to standardize their API approach.

When to Choose OData:

  • When building data-centric APIs with complex query requirements
  • When standardization and interoperability are important
  • When you want to reduce the number of custom API endpoints
  • When clients need flexibility in how they access data
  • When you want built-in features like filtering, sorting, and pagination

When to Consider Alternatives:

  • For very simple APIs with limited query requirements
  • When API performance is the highest priority
  • When you need fine-grained control over API behavior
  • When you’re building non-CRUD focused APIs
  • When you prefer a more custom approach to API design

Additional Resources