Terminology

ID

An ID is an URI used to identify a Higgs API Endpoint, such as a Service, Resource or Resource List. It is made up of an Account ID, followed by a Service Path and any parameter values, called arguments.

For example, to utilize the Classification API Service, the Resource ID would be https://{accountId}/Classification/{parent}/{key}.

All are Higgs URIs are also guaranteed to be working URLs URI is the more commonly known specification, however, Higgs supports IRI.

Key

A Key is an public identifier for each Instance of metadata or data belonging to a Service.

The following demonstrates how Keys are used to identify an Account, Classification and ancestor Classifications. 

https://higgs.online/account/{accountKey}/Classification/{ancestoryKey(s)}/{classKey}

Account

Each Backend is encapsulated within a registered Account. Higgs provides a globally accessible public account called public which is available at https://higgs.online/account/public.

Account ID

An Account ID start every Higgs Higgs ID. Account URIs identify the Backend to be used. The Higgs API specification, with each Service having their own Service Path, is independently accessible for each Account by appending to the Account ID.

The Account ID Template is higgs.online/account/{accountKey}.

Resource

A Resource is any Higgs Platform API Endpoint which has the representation of some knowledge, information and/or data. All Resources come with a standard set of Description Properties. Higgs automatically assigns and manages most Description Properties.

Name Description
^id The URI identifier of the Resource.
key The key used to access the Resource. Keys are unique to the Service the Resource is created from.
^type The type set the Resource is an instance of.
*label A text label used to name the Resource.
*comment Text used to further describe the Resource.
lang The language tag associated with the Resource. Each Resource has a representation on eachpossible language tag. This defaults to null/no language associated.
^owner The Account which owns the Resource. This is assigned by the Higgs Reasoner as the Account which created the Resource.
^version The version number of the Resource. Higgs will automatically store your last 3 versions.
^origin The Account which the Resource originated from.
^dateTimeCreated The date and time the Resource was created.
^lastModified The date and time of the last modification made to the Resource. 
* Optional Property
^ Automated Value Assignment

Service

A Service is any Function or Resource set operable using the Higgs API. These currently include: Classifications, Things, Properties, Schemas, Entities, Functions,

Each Service will have a URI template similar to: https://{accountId}/{servicePath}. The variations all come with the different ways to pass arguments for the Service-specific parameters.

Each Service will have it's Index accessible via the index keyword: https://{hostUri}/{servicePath}/index. This index simply orders the Instance members of the Service by the dateCreated field. For further indexing and searching, use the Search Service.

Service Path

A Service Path is a relative URI which is controlled by the Service it represents. Service Paths will typically use the following URI Template: /{serviceName}{/params}{?params}

Definition

A Higgs Definition is a Schema construct that allow users to create the Data Instances of a Knowledge Graph. Definitions are based on RDF Schema. At this current time, Higgs provides 3 primary Definitions which can be used to build Instances: Literals, Classifications and Relations. The Higgs Reasoner will coerce Instances against their given Definitions or Infer a best matched available Definition. Definitions are comparable to Data Definitions and/or Class definitions in traditional data modeling technologies.

Classification

Classifications are a Definition that allows authors to define a set of Things within a Taxonomy. This provides Higgs the descriptions necessary to enforce a type definition on things on Things. A Classification has a Parent Classification in which it inherits its Relations from.

Class Path

A Class path represents the ancestry or hierarchy of parents that the Class is extended from.

Resource Path

A Resource path is the Class Path followed by the Resource key. The template looks like: {classPath}/{resourceKey}

Relations

A Relation is a Directed Labeled Graph (DLG) that defines the Range of values for a particular Classification, called the Domain, under a Term which can be used to create Properties.

Data Instances

A Data Instance is a data value Resource which represents a single member of a declared Definition set called its type. A Literal is an instance of a Datatype. A Thing is an instance of a Classification. A Property is an instance of a Relation.

Schemas

A Schema is the set of all Definitions within an Account. Specifically, these are all the Classifications and Relations within a particular Account.

Diagram: Example Schema

In the above example, the Schema contains Publication and Author Classifications as well as title, dateOf, title and author Relations.

Resource Operations

All Resource Endpoints come equipped with Create, Read, Update and Delete (CRUD) Operations.

Functions

Functions are built-in Services available to each Resource with a pre-defined task ready for use.

Parameters

Parameters describe the input arguments API users can provide to each Endpoint.

URI Templates

URI Templates describe the how API users can call and provide input arguments to Higgs API Endpoints to retrieve a Web Resource. See RFC 6570

Request Templates

Request Templates describe how a HTTP Request can be formed for a particular Service. It uses the URI Template syntax.

Entity

An Entity is a Thing and its properties. Things will always be an instance of some Classification. A Property will always be an instance of some Relation.

Media Types

Also referenced as Content Type or MIME Type, this describes the content format and/or file type. Higgs supports the following Content Types:

Supported Response Types

  • text/html
  • application/json
  • application/ld+json
  • application/x-turtle
  • application/rdf+xml

Supported Request Body Types

  • application/json
  • application/ld+json
  • application/x-turtle
  • application/rdf+xml

Language Tag

Every Resource Instance