Entry point

Story

As an application user I want my application to consume an entry point for the Web API by providing a base URL So I can start managing my events.

Usage

const entryPoint = await hydraClient.getApiDocumentation("http://example.com/").getEntryPoint();

// Gather operations exposed by first-level hypermedia controls
for (const operation of entryPoint.hypermedia.where(_ => _.operations.any())) {
    // do something with the *operation*
}

// Gather collections
for (const collection of entryPoint.hypermedia.collections) {
    const add = collection.operations.ofType("http://schema.org/AddAction");
    if (add !== null) {
        // do something with the *collection*
    }
}

Details

It is simple to imagine a situation, when an application has a base URL provided, i.e. in a configuration or in the input field. Once provided, the application is expected to connect to the entry-point of the Web API and download initial details on what else can be done with that API from that very point.

GET /api

HTTP 200 OK

{
  "@context": "/api/context.jsonld",
  "@id": "/api",
  "@type": "EntryPoint",
  "collection": [
    {
      "@id": "/api/events",
      "title": "List of events",
      "@type": "Collection",
      "manages": {
        "property": "rdf:type",
        "object": "schema:Event"
      },
      "operation": {
        "@type": ["Operation", "schema:CreateAction"],
        "title": "Create new event",
        "method": "POST",
        "expects": "schema:Event"
      }
    },
    {
      "@id": "/api/people",
      "title": "List of people",
      "@type": "Collection",
      "manages": {
        "property": "rdf:type",
        "object": "schema:Person"
      },
      "operation": {
        "@type": ["Operation", "schema:CreateAction"],
        "title": "Create new person",
        "method": "POST",
        "expects": "schema:Person"
      }
    },
    {
      "@id": "/api/venues",
      "title": "List of venues",
      "@type": "Collection",
      "manages": {
        "property": "rdf:type",
        "object": "schema:Place"
      },
      "operation": {
        "@type": ["Operation", "schema:CreateAction"],
        "title": "Create new venue",
        "method": "POST",
        "expects": "schema:Place"
      }
    }
  ]
}

Note: The events property would need to be specified by the API. Hydra currently doesn't define any concepts which would allow to reference collections and describe their items in more details.

With this details, client application is aware of two possible operations that can be made from that point:

• GET events
• POST an event

It is possible for a rich UI application with some fancy logic that would takes all GET operations returning Collection and displays them in a main menu.

Considerations

RDFS entailment and OWL Reasoning capabilities

Another thing is how far the client should be pushed into the reasoning process. In the example above, both operations have their type explicitly expressed with "@type" keyword. But in RDFS environment, it is possible to use only method and expects predicates, which is fully legal as the entailment process would extend the resource /events with additional statement (in Turtle):

[] a hydra:Operation .

This is due to fact that Hydra Core Vocabulary provides an rdfs:domain for method . Unfortunately, many clients, especially browser based, won't use that process of entailment, thus an explicit statement should appear so the client can easily discover all the operations.

Security considerations

Please refer to the security considerations document.