on ASP.NET Web API, REST, ASP.NET, Web API

RESTful API design - how to best represent child entities? - Ask Schneids

I recently got an email from a friend of a friend asking me to advise them on a REST API they were designing.  I’ll happily give you advice, I reply.  Would you mind if I posted it for others to benefit?  He replied, yes, go ahead!

I think I’m going to make this a regular thing and call it Ask Schneids.  Feel free to email me your questions (or contact me any way you like – just make sure to include Ask Schneids somewhere in the body or subject so I know it’s okay to post) and I’ll respond to them and post the answers to this blog.  I’ll make sure to remove any identifying information from the question before I post it.

Anyways, without further ado, here’s my very first Ask Schneids question regarding RESTful API design.  Comments and follow up questions are always welcome – if you disagree, leave a comment below so we can all learn together! 🙂

How do you best return related entities?

I’m starting on a major refactoring, you could call it a rewrite, and one of my goals is to create an “API first” application using ASP.NET Web API and Entity Framework.

Our data is highly relational and I’m curious how to best return those complex objects/relations in JSON.  For example “inventory” is made from entities: “items”, “locations” and “unit of measure”, along with other properties like quantity, last change date, user, and other attributes to identify that specific instance of inventory.  “items” and ‘locations”  both have additional properties and related entities, the usual: name, description, etc, but can also include a list of images, a list of item aliases, among other things.

Basically my question is: how much of the related entity should be included when “inventory” is requested?  Just an Id, include the “core” info from the entity, or include the complete entity?  Of course it depends. 🙂

Of course it depends!  It always depends. 🙂  Typically it’s going to depend on your consumer.  Sounds like the API is going to consumed by both internal and external users.  Consider returning only a subset (or the “core”) of the most important data in a call with a related entity and expose an API that allows them to get more data if they request it.  For example, your inventory object might return the Item name and description, but allow you to get the additional data from the Item API if they need it.

I always recommend passing data from domain objects (e.g. objects specifically tied to a database, such as Entity Framework entities) to dumb DTOs (like view models, but for API’s) that are simple property bags.  You can use AutoMapper to do this quite easily.  Check out the Model Factory pattern here for an example (but don’t create the ModelFactory class and write all that repetitive, boring code – just use AutoMapper!)

Should you get individual records with the database ID or some other kind of unique identifier?

This is a multi-tenant app, and with that I’m struggling with whether or not to expose and use the system Id to the end user (PK of the entity in the database).  A user creates an item: Widget101, of course it gets and Id from the database, say 2345. Do you get the item like:

api/v1/items/2345
or
api/v1/items/Widget101

Best practice is to allow them to get the object via the database ID – it’s meaningful to your system and simpler for API construction.  If you need to expose a way to get the Item using another identifier (e.g. Widget101), consider using OData practices ($filter parameter would be a good place to start.)  You can find more information on implementing OData in ASP.NET Web API here.

For more REST implementation best practices, I really like Microsoft’s REST API guidelines found here.  They’re very comprehensive and are a good starting point for any REST API developer (ASP.NET or otherwise.)

Follow schneidenbach

on ASP.NET, Web API

Paging in ASP.NET Web API

Paging is a useful concept in any API.  Here’s an example of one that I use pretty frequently when making APIs in ASP.NET Web API.

You can download an example project (complete with unit tests!) here: https://github.com/schneidenbach/AspNetPagingExample

The steps we’re going to take to complete this task:

  • Setup our paging model.
  • Define our entity and API models.
  • Create our easy-to-use paging method that will magically turn an IQueryable into a paged set of data.

This example in particular requires AutoMapper, which will allow us to easily map our entities to our returned API models.  I also use Entity Framework to store and retrieve data, though that is not the focus of this particular project.  For the record – you should ALWAYS use API models (or DTOs, if you prefer) to do work through controllers.  Taiseer Joudeh, a Microsoft MVP for ASP.NET, calls it the “model factory pattern” and that’s how I typically refer to it.  That, or just API models. (Another way to think of API models: they hold the same purpose as a view model, but they’re not called that cause there’s no views.)  It’s a little bit more code up front, but will keep your code clean and enforce separation of concerns in the long run.  This has several advantages:

  • Lets you control what data is returned to the client.
  • Helps avoid binding to undocumented properties on PUTs/POSTs, which can be a pretty big security concern.
  • Maintains a separation of concerns. (This object returns data to the client, this object is a database entity, etc.)

1. Create and define a paging model.

We have our PageNumber and PageSize, which should match exactly what you requested (if you requested page 1 and page size 10, you should have a PageNumber of 1 and a PageSize of 10. These fields are included in the event you don’t want to require a page number or page size in your paged API.)

You have some Results, which represents the actual objects being returned.

There is a TotalNumberOfRecords and TotalNumberOfPages, which returns totals for the returned objects. If there are 100 total records and you’re requesting 15 records per page, you should expect that TotalNumberOfPages will return 7 pages.

Finally, one of the most useful properties in this model is NextPageUrl. NextPageUrl makes it very easy to get the next page in the set by providing the URL to that next resource for you.

2. Define your entities and your API models (you do use separate models for returning data, right?)

Note that in this example we are using Entity Framework for data storage.

3. Map them together using AutoMapper.

AutoMapper allows us to easily create the EmployeeModel from the Employee without writing and maintaining factory methods. All properties with the same name from Employee will be set on EmployeeModel. A lot of awesomeness in one little library.

4. Create the paged set of data.

I like to use the following CreatePagedResults method below on my controller base class – it does all of the heavy lifting for you.

A couple of important things to note:

  • The Url.Link method assumes that you have the default Web API route called DefaultApi setup in your RouteConfig.  If you don’t, you might have to tweak this example to work for you.
  • This example uses an extension method called OrderByPropertyOrField which (if you haven’t guessed) orders the IQueryable by the specified property, with a boolean to determine whether or not the order by should be ascending or descending. This string points to a property or field name of the entity type represented by IQueryable. The extension method is below:

Download the completed project here: https://github.com/schneidenbach/AspNetPagingExample