Features

Additional features

Adding this page really quickly - more prettiness to come.

Please look at the Tests to see what else this library can do

Qualified link relations

If a Resource class will use qualified link relations you have two options:

Just name the link relation with a fully qualified name, e.g.

person.Relations.Add("http://example.org/relations/foobar", GetLink());

Or you can add the qualifier to the Resource's Relations property:

person.Relations.AddQualifier("eg", "http://example.org/relations/{rel}");

Now that the Resource has this qualifier, you can build link relations like this:

person.Relations.Add("eg:foobar", GetLink());

That's all you have to worry about at Resource modelling time. The formatter will use this information and create qualified link relations using the capabilities of the media type. For example, HAL would emit the following:

{
  "name": "John Doe",
  "address": "123 Main St.",
  "_links": {
    "curies": [
      {
        "name": "eg",
        "href": "http://example.org/relations/{rel}",
        "templated": true
      }
    ],
    "eg:foobar": {
      "href": "http://example.org/api/foobar/321"
    },
    "self": {
      "href": "http://example.org/api/person/1"
    }
  }
}

If the media type does not support curries, the link relation would simply be named something like http://example.org/relations/foobar. XML flavoured media types can use this as to build an xmlns

Embedded resources

If you want to save clients the trouble of dereferencing a link relation just to get a commonly accessed value, you can embed a resource and provide that value.

For example, let's say we've found most clients traverse from Person to Car just to get the model of the car (e.g. Mustang). We can embed a Car property into the Person class:

public class Person : Resource
{
    public string Name { get; set; }
    public string Address { get; set; }
    public string Phone { get; set; }

    [NeverShow]
    public int MyCarId { get; set; }

    public Car Car { get; set; }
}

Then in the PersonController's Get() method (ultra simple here to demonstrate the idea)

[Route("api/person/{personId}", Name = "GetPersonById")]
public IHttpActionResult Get(int personId)
{
    var person = GetPersonFromRepository(personId);
    var car = GetCarFromRepository(carId);

    person.Relations.Add("car", 
        new Link
        {
            Href = Url.Link("GetCarById", new { carId = person.MyCarId })
        });

    person.Car = new Car {Model = car.Model};

    return Ok(person);
}

Which, when serialized to HAL becomes something like:

{
  "name": "John Doe",
  "address": "123 Main St.",
  "_links": {
    "car": {
      "href": "http://example.org/api/car/1"
    },
    "self": {
      "href": "http://example.org/api/person/1"
    }
  },
  "_embedded": {
    "car": {
      "model": "Mustang",
      "_links": {
        "self": {
          "href": "http://example.org/api/car/1"
        }
      }
    }
  }
}  

Lists

(coming soon)