property apiDocumentation is undefined

[johnslaughter-ihsmarkit]

Given this basic function:

async function example() {
  const { representation } = await Hydra.loadResource("https://sources.wikibus.org/book/1540");

  const resource = representation?.root; 
  
  if (!resource)
  {
    throw new Error("could not load resource");
  }
  
  const apiDocumentation = resource .apiDocumentation;
  console.log(apiDocumentation);
}

I'd expect to be able to reference the api documentation in this way. However, apiDocumentation accessed via the apiDocumentation property on a resource is always undefined.

[tpluscode]

I see how this may be confusing although it's technically by design.

See, the .apiDocumentation property essentially looks for hydra:apiDocumentation in the resource representation itself.

@base <https://sources.wikibus.org>

</book/1540> hydra:apiDocumenation </api> .

Hydra however delivers that as HTTP link header and this is why you don't get the value back from the getter.

I suppose it could be overloaded by Alcaeus to first try an explicit value of hydra:apiDocumenation and fall back to the http link if not found. However that way it becomes a precedent because no other getter behaves this way. WDYT?

[johnslaughter-ihsmarkit]

That makes sense. I think that there should be some built-in way to access a resources api documentation though (without needing to manually load it via the HTTP link header). Does that exist today?

[tpluscode]

Indeed there is. See Accessing all API Documentations

This should be enough in the simple app.

I realise however that this may be a little awkward in more complex scenarios. For example an application retrieving resources from multiple APIs will result in multiple objects in the apiDocumentations array and there is no easy way to tie any given resource back to its originating API as it came in the HTTP Link.

I will implement as proposed above to override apiDocumentation getter on all objects so that they return their own api documentation

[tpluscode]

Released in 1.4.0

I also figured that the linked docs section was kinda hidden so I moved it to the API Documentation page alongside a new paragraph for the change at hand

[tpluscode]

Meh, not so fast. I got punished for doing unit test but not integration. Re tpluscode/rdfine#183

Gotta update to 2.0 for a proper fix. Went for a major version because of breaking change upstream