- From: McBennett, Pat <McBennettP@DNB.com>
- Date: Wed, 30 Apr 2014 11:23:53 -0500
- To: "public-hydra@w3.org" <public-hydra@w3.org>
- Message-ID: <52EE3F4A5E7F194A963FE14B2DDBDBFE2B177D6266@DNBEXCH01.dnbint.net>
Hi all,
So I've just joined this Community Group (on behalf of D&B), and we've very enthusiastic about contributing ideas and learning from the wider group.
As I'm so new I thought I'd try and 'catch up' in terms of understanding Hydra. To prevent me asking dumb questions (at least initially!), I thought I'd start by trying to understand a canonical example of a Hydra Web API (even though 'canonical' will of course change as the group progresses).
So naturally enough I started with the Hydra Console and the Issue Tracker demo (which was a great thing to model as an example by the way!). But in fact I found it difficult to find the actual Hyrda JSON-LD that describes this Issue Tracker Web API.
Clicking around I came across the JSON-LD served up from 'http://www.markus-lanthaler.com/hydra/api-demo/vocab#' (which I've included pretty-printed below). But in talking directly to Markus (before joining this group), apparently this JSON-LD is generated dynamically, which leads into my first set of newbie questions:
1) Is the whole point of Hydra that any Web API would publish at least the description of its entrypoint as a single Hydra document (whose serialization might default to JSON-LD, but presumably could be in any RDF format, like Turtle, or N3, or whatever)?
a. Just for manageability, I assume a large sophisticated API could choose to publish individual parts of its API in separate Hydra documents (each of which would be pointed to from a single entrypoint API), but at least the entrypoint itself (i.e. the starting point) should be encoded in a single Hydra document?
2) If 1) is correct, then does the JSON-LD below really represent the Hydra API for the Issue Tracker Web API?
a. If it does, then I have a number of questions and suggestions, but I won't mention them yet.
b. If it isn't the definitive JSON-LD, then where is it...?
3) Or have I missed the point completely, and Hydra Web APIs aren't actually intended to be described in JSON-LD (or some other RDF representation), but the API description (for example the Issue Tracker JSON-LD below) is intended to be generated somehow from some other form?
Cheers,
Pat.
"@context": {
"vocab": "http://www.markus-lanthaler.com/hydra/api-demo/vocab#",
"hydra": "http://www.w3.org/ns/hydra/core#",
"ApiDocumentation": "hydra:ApiDocumentation",
"property": "hydra:property",
"readonly": "hydra:readonly",
"writeonly": "hydra:writeonly",
"supportedClasses": "hydra:supportedClasses",
"supportedProperties": "hydra:supportedProperties",
"supportedOperations": "hydra:supportedOperations",
"method": "hydra:method",
"expects": {
"@id": "hydra:expects",
"@type": "@id"
},
"returns": {
"@id": "hydra:returns",
"@type": "@id"
},
"statusCodes": "hydra:statusCodes",
"code": "hydra:statusCode",
"rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
"rdfs": "http://www.w3.org/2000/01/rdf-schema#",
"label": "rdfs:label",
"description": "rdfs:comment",
"domain": {
"@id": "rdfs:domain",
"@type": "@id"
},
"range": {
"@id": "rdfs:range",
"@type": "@id"
}
},
"@id": "http://www.markus-lanthaler.com/hydra/api-demo/vocab",
"@type": "ApiDocumentation",
"supportedClasses": [
{
"@id": "http://www.w3.org/ns/hydra/core#Resource"
},
{
"@id": "http://www.w3.org/ns/hydra/core#Collection"
},
{
"@id": "vocab:User",
"@type": "hydra:Class",
"label": "User",
"description": "A User represents a person registered in the system.",
"supportedOperations": [
{
"@id": "_:user_replace",
"method": "PUT",
"label": "Replaces an existing User entity",
"description": null,
"expects": "vocab:User",
"returns": "vocab:User",
"statusCodes": [
{
"code": 404,
"description": "If the User entity wasn't found."
}
]
},
{
"@id": "_:user_delete",
"method": "DELETE",
"label": "Deletes a User entity",
"description": null,
"expects": null,
"returns": "http://www.w3.org/2002/07/owl#Nothing",
"statusCodes": []
},
{
"@id": "_:user_retrieve",
"method": "GET",
"label": "Retrieves a User entity",
"description": null,
"expects": null,
"returns": "vocab:User",
"statusCodes": []
}
],
"supportedProperties": [
{
"property": {
"@id": "vocab:User/name",
"@type": "rdf:Property",
"label": "name",
"description": "The user's full name",
"domain": "vocab:User",
"range": "http://www.w3.org/2001/XMLSchema#string",
"supportedOperations": []
},
"required": null,
"readonly": false,
"writeonly": false
},
{
"property": {
"@id": "vocab:User/email",
"@type": "rdf:Property",
"label": "email",
"description": "The user's email address",
"domain": "vocab:User",
"range": "http://www.w3.org/2001/XMLSchema#string",
"supportedOperations": []
},
"required": null,
"readonly": false,
"writeonly": false
},
{
"property": {
"@id": "vocab:User/password",
"@type": "rdf:Property",
"label": "password",
"description": "The user's password",
"domain": "vocab:User",
"range": "http://www.w3.org/2001/XMLSchema#string",
"supportedOperations": []
},
"required": null,
"readonly": false,
"writeonly": true
},
{
"property": {
"@id": "vocab:User/raisedIssues",
"@type": "hydra:Link",
"label": "raised_issues",
"description": "The issues raised by this user",
"domain": "vocab:User",
"range": "http://www.w3.org/ns/hydra/core#Collection",
"supportedOperations": [
{
"@id": "_:user_raised_issues_retrieve",
"method": "GET",
"label": "Retrieves the issues raised by a User entity",
"description": null,
"expects": null,
"returns": "http://www.w3.org/ns/hydra/core#Collection",
"statusCodes": [
{
"code": 404,
"description": "If the User entity wasn't found."
}
]
}
]
},
"required": null,
"readonly": true,
"writeonly": false
}
]
},
{
"@id": "vocab:Issue",
"@type": "hydra:Class",
"label": "Issue",
"description": "An Issue tracked by the system.",
"supportedOperations": [
{
"@id": "_:issue_replace",
"method": "PUT",
"label": "Replaces an existing Issue entity",
"description": null,
"expects": "vocab:Issue",
"returns": "vocab:Issue",
"statusCodes": [
{
"code": 404,
"description": "If the Issue entity wasn't found."
}
]
},
{
"@id": "_:issue_delete",
"method": "DELETE",
"label": "Deletes a Issue entity",
"description": null,
"expects": null,
"returns": "http://www.w3.org/2002/07/owl#Nothing",
"statusCodes": []
},
{
"@id": "_:issue_retrieve",
"method": "GET",
"label": "Retrieves a Issue entity",
"description": null,
"expects": null,
"returns": "vocab:Issue",
"statusCodes": []
}
],
"supportedProperties": [
{
"property": {
"@id": "vocab:Issue/title",
"@type": "rdf:Property",
"label": "title",
"description": "The issue's title",
"domain": "vocab:Issue",
"range": "http://www.w3.org/2001/XMLSchema#string",
"supportedOperations": []
},
"required": null,
"readonly": false,
"writeonly": false
},
{
"property": {
"@id": "vocab:Issue/description",
"@type": "rdf:Property",
"label": "description",
"description": "A description of the issue",
"domain": "vocab:Issue",
"range": "http://www.w3.org/2001/XMLSchema#string",
"supportedOperations": []
},
"required": null,
"readonly": false,
"writeonly": false
},
{
"property": {
"@id": "vocab:isOpen",
"@type": "rdf:Property",
"label": "is_open",
"description": "Is the issue open?\nUse for 1 yes, 0 for no when modifying this value.",
"domain": "vocab:Issue",
"range": "http://www.w3.org/2001/XMLSchema#boolean",
"supportedOperations": []
},
"required": null,
"readonly": false,
"writeonly": false
},
{
"property": {
"@id": "vocab:Issue/raisedBy",
"@type": "hydra:Link",
"label": "raised_by",
"description": "The user who raised the issue",
"domain": "vocab:Issue",
"range": "vocab:User",
"supportedOperations": [
{
"@id": "_:user_retrieve",
"method": "GET",
"label": "Retrieves a User entity",
"description": null,
"expects": null,
"returns": "vocab:User",
"statusCodes": []
}
]
},
"required": null,
"readonly": true,
"writeonly": false
},
{
"property": {
"@id": "vocab:Issue/createdAt",
"@type": "rdf:Property",
"label": "created_at",
"description": "The date and time this issue was created",
"domain": "vocab:Issue",
"range": "http://www.w3.org/2001/XMLSchema#dateTime",
"supportedOperations": []
},
"required": null,
"readonly": true,
"writeonly": false
},
{
"property": {
"@id": "vocab:Issue/comments",
"@type": "hydra:Link",
"label": "comments",
"description": "The comments associated with this issue",
"domain": "vocab:Issue",
"range": "http://www.w3.org/ns/hydra/core#Collection",
"supportedOperations": [
{
"@id": "_:issue_comment_create",
"method": "POST",
"label": "Creates a new Comment for a specific issue",
"description": "To create a new Comment you have to be authenticated.",
"expects": "vocab:Comment",
"returns": "vocab:Comment",
"statusCodes": [
{
"code": 404,
"description": "If the Issue wasn't found."
}
]
},
{
"@id": "_:issue_comment_collection_retrieve",
"method": "GET",
"label": "Retrieves all Comment entities for a specific issue",
"description": null,
"expects": null,
"returns": "http://www.w3.org/ns/hydra/core#Collection",
"statusCodes": []
}
]
},
"required": null,
"readonly": true,
"writeonly": false
}
]
},
{
"@id": "vocab:Comment",
"@type": "hydra:Class",
"label": "Comment",
"description": "Comment",
"supportedOperations": [
{
"@id": "_:comment_replace",
"method": "PUT",
"label": "Replaces an existing Comment entity",
"description": null,
"expects": "vocab:Comment",
"returns": "vocab:Comment",
"statusCodes": [
{
"code": 404,
"description": "If the Comment entity wasn't found."
}
]
},
{
"@id": "_:comment_delete",
"method": "DELETE",
"label": "Deletes a Comment entity",
"description": null,
"expects": null,
"returns": "http://www.w3.org/2002/07/owl#Nothing",
"statusCodes": []
},
{
"@id": "_:comment_retrieve",
"method": "GET",
"label": "Retrieves a Comment entity",
"description": null,
"expects": null,
"returns": "vocab:Comment",
"statusCodes": []
}
],
"supportedProperties": [
{
"property": {
"@id": "vocab:Comment/text",
"@type": "rdf:Property",
"label": "text",
"description": "The comment",
"domain": "vocab:Comment",
"range": "http://www.w3.org/2001/XMLSchema#string",
"supportedOperations": []
},
"required": null,
"readonly": false,
"writeonly": false
},
{
"property": {
"@id": "vocab:Comment/issue",
"@type": "hydra:Link",
"label": "issue",
"description": "The issue this comment belongs to",
"domain": "vocab:Comment",
"range": "vocab:Issue",
"supportedOperations": [
{
"@id": "_:issue_retrieve",
"method": "GET",
"label": "Retrieves a Issue entity",
"description": null,
"expects": null,
"returns": "vocab:Issue",
"statusCodes": []
},
{
"@id": "_:issue_replace",
"method": "PUT",
"label": "Replaces an existing Issue entity",
"description": null,
"expects": "vocab:Issue",
"returns": "vocab:Issue",
"statusCodes": [
{
"code": 404,
"description": "If the Issue entity wasn't found."
}
]
}
]
},
"required": null,
"readonly": true,
"writeonly": false
},
{
"property": {
"@id": "vocab:Comment/user",
"@type": "hydra:Link",
"label": "user",
"description": "The user who wrote this comment",
"domain": "vocab:Comment",
"range": "vocab:User",
"supportedOperations": [
{
"@id": "_:user_retrieve",
"method": "GET",
"label": "Retrieves a User entity",
"description": null,
"expects": null,
"returns": "vocab:User",
"statusCodes": []
}
]
},
"required": null,
"readonly": true,
"writeonly": false
},
{
"property": {
"@id": "vocab:Comment/createdAt",
"@type": "rdf:Property",
"label": "created_at",
"description": "The date and time this comment was created",
"domain": "vocab:Comment",
"range": "http://www.w3.org/2001/XMLSchema#dateTime",
"supportedOperations": []
},
"required": null,
"readonly": true,
"writeonly": false
}
]
},
{
"@id": "vocab:EntryPoint",
"@type": "hydra:Class",
"label": "EntryPoint",
"description": "The main entry point or homepage of the API.",
"supportedOperations": [
{
"@id": "_:entry_point",
"method": "GET",
"label": "The APIs main entry point.",
"description": null,
"expects": null,
"returns": "vocab:EntryPoint",
"statusCodes": []
}
],
"supportedProperties": [
{
"property": {
"@id": "vocab:EntryPoint/issues",
"@type": "hydra:Link",
"label": "issues",
"description": "The collection of all issues",
"domain": "vocab:EntryPoint",
"range": "http://www.w3.org/ns/hydra/core#Collection",
"supportedOperations": [
{
"@id": "_:issue_create",
"method": "POST",
"label": "Creates a new Issue entity",
"description": null,
"expects": "vocab:Issue",
"returns": "vocab:Issue",
"statusCodes": [
{
"code": 201,
"description": "If the Issue entity was created successfully."
}
]
},
{
"@id": "_:issue_collection_retrieve",
"method": "GET",
"label": "Retrieves all Issue entities",
"description": null,
"expects": null,
"returns": "http://www.w3.org/ns/hydra/core#Collection",
"statusCodes": []
}
]
},
"required": null,
"readonly": true,
"writeonly": false
},
{
"property": {
"@id": "vocab:EntryPoint/registerUser",
"@type": "hydra:Link",
"label": "register_user",
"description": "IRI to register a new user",
"domain": "vocab:EntryPoint",
"range": "http://www.w3.org/ns/hydra/core#Resource",
"supportedOperations": [
{
"@id": "_:user_create",
"method": "POST",
"label": "Creates a new User entity",
"description": null,
"expects": "vocab:User",
"returns": "vocab:User",
"statusCodes": [
{
"code": 201,
"description": "If the User entity was created successfully."
}
]
}
]
},
"required": null,
"readonly": true,
"writeonly": false
},
{
"property": {
"@id": "vocab:EntryPoint/myAccount",
"@type": "hydra:Link",
"label": "my_account",
"description": "If logged in, a link to the user account",
"domain": "vocab:EntryPoint",
"range": "vocab:User",
"supportedOperations": [
{
"@id": "_:user_retrieve",
"method": "GET",
"label": "Retrieves a User entity",
"description": null,
"expects": null,
"returns": "vocab:User",
"statusCodes": []
}
]
},
"required": null,
"readonly": true,
"writeonly": false
},
{
"property": {
"@id": "vocab:EntryPoint/users",
"@type": "hydra:Link",
"label": "users",
"description": "The collection of all users (for debugging purposes)",
"domain": "vocab:EntryPoint",
"range": "http://www.w3.org/ns/hydra/core#Collection",
"supportedOperations": [
{
"@id": "_:user_create",
"method": "POST",
"label": "Creates a new User entity",
"description": null,
"expects": "vocab:User",
"returns": "vocab:User",
"statusCodes": [
{
"code": 201,
"description": "If the User entity was created successfully."
}
]
},
{
"@id": "_:user_collection_retrieve",
"method": "GET",
"label": "Retrieves all User entities",
"description": null,
"expects": null,
"returns": "http://www.w3.org/ns/hydra/core#Collection",
"statusCodes": []
}
]
},
"required": null,
"readonly": true,
"writeonly": false
}
]
}
]
}
[cid:image001.png@01CF6494.50875EA0]<http://www.dnb.com/uk>
Pat McBennett
Architect
Direct Dial: +353 1 256 6082
D&B Business Information Solutions
Address: The Chase (5th Floor), Carmanhall Road, Sandyford, Dublin 18 (Ireland)
Attachments
- image/png attachment: image001.png
Received on Wednesday, 30 April 2014 16:24:32 UTC