Complete API documentation

Story

As a API consumer I want to be able to get an extensive description of the API's data structures and capabilities so that I can use API testing tools, make some client-side pre-computations or create a documentation out of it.

Details

Hydra is an RDF vocabulary, thus it is enabled to provide extensive meta-data descriptions for both payload embedded and entry-point level hypermedia controls. While it may be impossible to provide as rich description as in case of the embedded description, still API documentation should be capable to provide extensive details about API for various usages. These descriptions should cover:

• supported classes with:
  • name
  • description
  • super-classes
  • supported properties with:
    • name
    • description
    • cardinality
    • value type constraints (if any)
  • supported operations with:
    • name
    • description
    • request details (method, expected payload, returned payload, etc.)

Example of such a description may be as follows (in Turtle syntax):

@prefix hydra: <http://www.w3.org/ns/hydra/core#> .
@prefix schema: <http://schema.org/> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix owl: <http://www.w3.org/2002/07/owl#> .
@prefix vocab: <http://vocab.temp.uri/api#> .

</apiDocumentation> a hydra:ApiDocumentation;
    hydra:entrypoint </> ;
    hydra:title "Hydra example API." ;
    hydra:description "Some example API described using Hydra vocabulary" ;
    hydra:supportedClass schema:Event, schema:Person ;

schema:Event a hydra:Class ;
    hydra:supportedOperation <#get-events-operation> ,
        <#new-event-operation> ;
    hydra:supportedProperty [
        a hydra:SupportedProperty ;
        hydra:propety vocab:id ;
        hydra:required "true"^^xsd:boolean ;
        hydra:writable "true"^^xsd:boolean ;
        hydra:readable "true"^^xsd:boolean ] ;
    hydra:supportedProperty [
        a hydra:SupportedProperty ;
        hydra:propety schema:name ;
        hydra:required "true"^^xsd:boolean ;
        hydra:writable "true"^^xsd:boolean ;
        hydra:readable "true"^^xsd:boolean ] ;
    hydra:supportedProperty [
        a hydra:SupportedProperty ;
        hydra:propety schema:description ;
        hydra:required "true"^^xsd:boolean ;
        hydra:writable "true"^^xsd:boolean ;
        hydra:readable "true"^^xsd:boolean ] ;
    hydra:supportedProperty [
        a hydra:SupportedProperty ;
        hydra:propety schema:startDate ;
        hydra:required "true"^^xsd:boolean ;
        hydra:writable "true"^^xsd:boolean ;
        hydra:readable "true"^^xsd:boolean ] ;
    hydra:supportedProperty [
        a hydra:SupportedProperty ;
        hydra:propety schema:endDate ;
        hydra:required "true"^^xsd:boolean ;
        hydra:writable "true"^^xsd:boolean ;
        hydra:readable "true"^^xsd:boolean ] .

# Below are operations related to schema:Event supported class.
# Unfortunately, it is not possible to link them directly to the supported class
# as the hydra:Operation does not allow to define the URL to be invoked.
# Maybe when either actions or request templates are introduced will enable this feature,
# as discussed in #154.

# The link below does not allow to describe the fact returned payload is a collection of schema:Event,
# thus the only hint for the client to connect it with that class is comparing supported operations 
# defined in this link and the class itself.
</events> a hydra:Link ;
    hydra:title "Obtains a collection of events." ;
    hydra:supportedOperation <#new-event>, <#get-events> .

<#get-events-operation> a hydra:Operation ;
   hydra:method "GET"^^xsd:string ;
   hydra:possibleStatus "200"^xsd:int, "500"^^xsd:int ;
   hydra:returns hydra:Collection .

<#new-event-operation> a hydra:Operation, schema:CreateAction ;
    hydra:expects schema:Event ;
    hydra:method "POST"^^xsd:string
    hydra:possibleStatus "200"^xsd:int, "500"^^xsd:int .

# Link with operation below does not mention directly that no value is returned.
# Only hint of that may be taken from the 201 status.
# As of the connection with schema:Event - it is mentioned as an expected class.
# It is also impossible to use hydra:memberTemplate in conjuction with the schema:Event collection link.
# An issue #167 was rised in order to address this.
<#direct-event> a hydra:TemplatedLink ;
    hydra:template "http://temp.uri/api/events/{id}"^^hydra:Rfc6570Template ;
    hydra:mapping <#id-mapping> ;
    hydra:supportedOperation [
        a hydra:Operation, schema:UpdateAction ;
        hydra:title "Updates an event." ;
        hydra:method "PUT"^^xsd:string ;
        hydra:possibleStatus "201"^xsd:int, "404"^^xsd:int, "500"^^xsd:int ;
        hydra:expects schema:Event
    ], [
        a hydra:Operation, schema:DeleteAction ;
        hydra:title "Deletes an event." ;
        hydra:method "DELETE"^^xsd:string ;
        hydra:possibleStatus "201"^xsd:int, "404"^^xsd:int, "500"^^xsd:int
    ].

<#id-mapping> a hydra:IriTemplateMapping ;
    hydra:variableRepresentation: hydra:BasicRepresentation ;
    hydra:variable "id"^^xsd:string ;
    hydra:property vocab:id ;

vocab:id a rdf:Property ;
    rdf:domain schema:Event ;
    rdf:range xsd:int .

It is currently impossible to describe expected or returned cardinality of the links/operations gathered above. Both hydra:returns and hydra:expects are allowed to receive statements related to multiple resources of same type. While for PUT operations server may use only statements related to the resource identified by the call's URL, in case of POST where the resource will have no explicit identifier server may end up with an 4XX or some other unexpected behavior.