Data and metadata available to the web API designer and user

This is a brief reminder of the list of data items and metadata that are available to web service designers and users.

HTTP method

URI

Request headers

Response headers

Message body, in general

Representation (of a resource)

Today, you will learn something about these:

Link relations

HTTP OPTIONS method

Representations that enable a user/requestor to add a resource

.

A brief discussion of ‘links’…

Web client programmers are familiar with the ‘link’ element ( <a> ) in HTML. You also know that the “HT” part of HTML expands to “hypertext”.

What’s at the other end of a link in HTML? Text? Always? Or can it be an image, a video, or some other media?

So, just change your understanding a bit, so that a link is a ‘hypermedia’ link, and not just a hypertext link.

In a web API, links are used to tell the requestor about state transitions. In other words, they tell the requestor what can be done next.

For example, assume that a requestor asks for a single-item resource. The web service returns a representation (the data) for that resource. It would be nice to include data and/or metadata that would tell the requestor whether that resource could be modified, or deleted. Or whether it was possible to add a new resource to the resource’s parent/collection.

.

Link relations

The solution is to use link relations. Using this solution, the response includes links that can guide the user through state transitions.

A link is a data object, delivered in-band, with the representation. When you define a link in a web service, you must also define its relationship to the current object.

For example, a single object must include a link to itself:

The value of the URI (aka href) will be the item’s URI

The value of the relationship (aka rel) will be ‘self’

If it’s part of a collection, it must also include a link to its parent/collection:

The value of the URI (aka href) will be the item’s parent/collection

The value of the relationship (aka rel) will be ‘collection’

This design ensures that the responses from your web service are self-describing.

The IANA has published a list of standardized link relations. You can create your own, but use the standard link relations until you gain more experience.

.

Code example for today’s topics

From the code example repository, look at LinkRelationsIntro.

.

Preview of our design and coding plan

In general, we will follow these steps:

Start with an existing project that works well.

Add new ‘view model’ classes that support and enable link relations.

For an entity, add new ‘view model’ classes that include link relations. Add new AutoMapper definition(s).

Update ‘controller’ code. Wrap the fetch result(s) in a view model class that includes link relations, and configure the links.

Add support for the HTTP ‘OPTIONS’ method.

Configure an entry point URI for the web service.

.

Are there standards (for expressing link relations) that we must follow? No.

In today’s example, we create our own representations.

In the future, we may look at HAL and/or Collection+JSON. It’s possible that you may use one of those in the future (or design your own).

.

Start with an existing project that works well

You will learn this topic more effectively if you use an existing project that works well.

Create a copy of that project, using the copy-then-rename technique you learned a few weeks ago.

.

Add new ‘view model’ classes that support and enable link relations

Create a new source code file – perhaps named VM_Link – to the ViewModels folder.

It will hold classes that support and enable link relations.

.

Overview of the design

There will be two versions of our class that supports link relations: 1) one item, and 2) collection of items.

For one item (click the image to see it full-size in a new tab/window):

The class has two properties, ‘Links’ and ‘Item’

‘Links’ is a collection of one or more Link objects

One Link is to ‘self’

Another Link is to its parent ‘collection’

‘Item’ is the actual fetched result

The ‘Item’ also includes a Link to ‘self’

For a collection of items (click the image to see it full-size):

The class has two properties, ‘Links’ and ‘Collection’

‘Links’ is a collection of one or more Link objects

One Link is to ‘self’

‘Collection’ is the actual fetched results

Each ‘Item’ in the collection includes a Link to ‘item’

.

Write the classes

We will need a Link class to model a hyperlink. At a minimum, it will need href and rel properties.

If you wished, in a future project, you could consider adding other properties, such as title, method, and type.

.

Abstract class in C#

It’s possible that you have not written an abstract class yet.

An abstract class is use used as a base class that another class inherits from. By itself, that’s nothing special.

Our situation is different. In our app domain data model, it’s possible that we may have a large number of ‘entity’ classes. Then, for each entity class, we will have some ‘view model’ classes.

An abstract class will reduce the amount of code we write, if we also take advantage of generics and type injection. So, let’s do that: Write an abstract class, for a single item, that includes a T (type) parameter, as shown below:

.

Do the same to create an abstract class for a collection of items.

.

For an entity, add new ‘view model’ classes that include link relations
Add new AutoMapper definition(s)

Our goal is to add a Link property to a suitable view model class. That’s easy.