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.
var client = new HydraClient();
var entryPoint = client.get("http://example.com/").getEntryPoint();
for (var operation of entryPoint.operations) {
// do something with the *operation*
}
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": "hydra:EntryPoint",
"collection": {
"@id": "/api/events",
"title": "List of events",
"@type": "hydra:Collection",
"manages": {
"property": "rdf:type",
"object": "schema:Event"
},
"operation": [
{
"@type": ["hydra:Operation", "schema:CreateAction"],
"title": "Create new event",
"method": "POST",
"expects": "schema:Event"
}
]
}
}
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 hydra:Collection and displays them in a main menu.
Another thing is how far the client should be pushed into the reasoning process. In the example above, both operations have their type explicitely expressed with "@type" keyword. But in RDFS environment, it is possible to use only hydra:method and hydra: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 hydra: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.
Please refer to the (this)[/1.1.security-considerations.md] for security considerations.