This repository contains work in progress for an architecture diagram of the Hydra Core Vocabulary.
An arrow represents a dependency from a component on another.
Web APIs consist of resources and collections.
- structural description of an API
- metadata of an API
Resources are the atoms of (Hydra-enabled) REST Web APIs.
Resources can have one or more representations. If those representations are RDF-based formats (or support embedding RDF), then they describe the resource using elements from the Hydra Core Vocabulary.
- how resources can incorporate Hydra descriptions and/or controls
- in particular, how descriptions and controls can be separated from data
- describing representations
- properties that a resource representation will list
- on Errors, since resources can generate errors
Collections are sets of resources and associated behavior.
Collections can contain zero or more resources. Collections are resources themselves.
- describing kinds of collections
- properties of their elements (type etc.)
- describing representations
- (optional) properties of resources that a collection representation will list
- describing operations on collections
- creation
- addition
- deletion
- on Resources, since a collection is a resource and contains resources
Errors describe what can go wrong during the interaction with a resource, and possible ways to address it.
- types of errors
- error metadata
- possible causes
- possible fixes
- connecting errors to resources
none
Fields are places where clients can provide input.
- parameter description
- name
- constraints
- range
- validation
none
URI Templates express how field values are combined into an URL.
- field serialization
- on Fields, since they are needed to fill out templates
Entity Bodies express how field values are combined into a request body (e.g., for POST/PUT/PATCH).
- entity structure
- JSON-LD and other RDF formats
- non-RDF formats
- field serialization
- on Fields, since they are needed to fill out entity bodies
Pages partition collections into subsets such that each child resource appears on exactly one page.
Pages (only) change application state.
- page navigation
- next, previous
- first, last
- jump to specific page
- page metadata
- current page number
- total number of pages
- number of items per page
- ordering
- based on resource attributes
- client-initiated paging
- determine ordering
- determine number of items per page
- on Collections, since they are being paged
- on URI Templates, since some paging options require generating a page URI
Filters select subsets of collections based on resource attributes.
Filters (only) change application state.
- availability of filters
- conditions for applying a filter
- the effect of a filter
- how a filter maps input values to a selection
- on Collections, since they are being filtered
- on URI Templates, since some filters require generating a page URI
- on Fields, since they relate the filter to its effect
Actions express manipulations of resources through representations.
Actions change resource state.
- availability of actions
- conditions for executing an action
- the effect of executing an action
- on Resources, since actions can be executed on them
- on Collections, since actions can be executed on them
- on Fields, since they relate the action to its effect
- on Entity Bodies, since some actions require sending a request body