BC break in v1.8.0+ related to hypermedia links

[evsheffield]

It seems that there may have been a backwards-compatible break introduced in 1.8.0 that causes issues generating hypermedia links for certain configurations. For example, here is a setup that worked in 1.7.0 but seems incompatible with later versions:

Document Context resource type configuration

protected override void OnServiceModelCreating(IServiceModelBuilder serviceModelBuilder)
{
    var inodeConfiguration = serviceModelBuilder.Resource<ReportINodeSummary>();
    inodeConfiguration.Hypermedia().SetApiCollectionPathSegment("api/inodes");
    inodeConfiguration.ResourceIdentity(x => x.Id).SetApiType("inodes");
    ...
}

Document Creation

var document = new ReportingDocumentContext(currentUri)
        .NewDocument(currentUri)
            .Links()
                .AddSelfLink()
            .LinksEnd()
            .ResourceCollection(inodeSummaries)
            .ResourceCollectionEnd()
            .WriteDocument();

In v1.8.0 and above, this results in the following error: System.InvalidOperationException: Sequence contains no elements, which seems to be linked to the presence of AddSelfLink().

   at System.Linq.Enumerable.Last[TSource](IEnumerable`1 source)
      at JsonApiFramework.Server.Hypermedia.Internal.DocumentPathContext.GetPrimaryClrResourceType()
      at JsonApiFramework.Server.Hypermedia.HypermediaAssembler.CreateStandardDocumentLink(IHypermediaContext hypermediaContext, IDocumentPathContext documentPathContext, ILinkContext linkContext)
      at JsonApiFramework.Server.Hypermedia.HypermediaAssembler.CreateDocumentLink(IHypermediaContext hypermediaContext, IDocumentPathContext documentPathContext, DocumentType documentType, ILinkContext linkContext)
      at JsonApiFramework.Server.Internal.DocumentBuilder.ResolveDocumentHypermedia()
      at JsonApiFramework.Server.Internal.DocumentBuilder.WriteDocument()

However, it seems that adding the following configuration for a new type to OnServiceModelCreating (adapted from your example repository) clears up the issue.

var apiEntryPointConfiguration = serviceModelBuilder.Resource<ApiEntryPoint>();
apiEntryPointConfiguration.Hypermedia().SetApiCollectionPathSegment("api");
apiEntryPointConfiguration.ResourceIdentity().SetApiType("api-entry-point");

I'm unsure if this is a bug or simply my lack of understanding of DocumentContext and resource configuration requirements of the latest versions. Any guidance would be much appreciated!

[scott-mcdonald]

@evsheffield Sorry about the breaking change as I tried to avoid such things. First question I have, is the path segment "api" at the root of all your Web API routes?

[evsheffield]

Hi @scott-mcdonald, thanks for the quick reply! Yes, the "api" path segment is at the root of all of our API routes.

[scott-mcdonald]

@evsheffield A couple of comments.

• I would suggest if "api" is essentially a root path segment meaning something like "http://api.example.com/api" is the root of all hypermedia then add "api" as a root path segment wherever you are creating the UrlBuilderConfiguration object in your code base. Then you do not have to keep adding "api" manually and your configuration changes from SetApiCollectionPathSegment("api/inodes") to SetApiCollectionPathSegment("inodes") where the hypermedia building engine will automatically add the "api" to all hypermedia built. In addition, this explicitly defines for the framework that "api" is not part of hypermedia path building when the framework is "reverse engineering" the paths to figure out what resource types are in play for the current request.
• This is a new feature but to support a home document that is a singleton meaning it doesn't need an identifier because there is only 1, then yes use the ResourceIdentity().SetApiType("api-entry-point") without specifying any identifier which is how you configure a "singleton" resource that doesn't need an Id. Also inform the framework what is the home resource type by calling HomeResource<ApiEntryPoint>(). If your "api-entry-point" is a home document where "id" doesn't make sense then configure as I mentioned here and how I did the same thing in the Samples project.

Let me know if this resolves your problem.

[scott-mcdonald]

@evsheffield Also, upgrade to v1.9 as well which is the latest version and the version the current Samples project is built off of that I mentioned in the previous post.

[evsheffield]

@scott-mcdonald I made sure we are on the latest version and configured "api" as a root segment in the UrlBuilderConfiguration instead of manually in each collection path as you recommended and that did the trick. 👍 Thanks so much for your help!