API Usage Guide

 

Introduction

This documentation refers to Version: 1.0.0 of the HIASHDI component.

The HIASHDI Console is a REST API client for HIASHDI that is built in to the HIAS UI. The console has been designed to provide the functionalty required to interact with HIASHDI using the methods provided in the following API usage guide.

PLEASE NOTE: API and functionality is not yet complete.

 

Overview

The following is the API Documentation for the HIASHDI API. This API is based on the specifications provided in the FIWARE-NGSI v2 Specification.

 

Secure HTTP Requests

API calls to the HIASHDI API are made using secure HTTP requests. The HIAS server protects the API endpoints with strong SSL encryption, a firewall and Basic AUTH authentication.

The following HTTP request methods are available:

 

HTTP Responses

HTTP Success Response

HTTP Success Codes

HTTP Error Response

The error payload is a JSON response including the following fields:

HTTP Error Codes

 

Authentication

Authentication is handled using the HIAS server security. Calls to HIASHDI must provide a HIAS user's key (YourKey below) in the Authorization header, authorization type Basic. A HIAS user's key is generated by joining the username and password with a : separating them, and then Base64 encoding the key.

headers = {
    "Content-Type": "application/json",
    "Authorization": "Basic YourKey"
}

 

API Resources

Retrieve API Resources

This resource does not have any attributes. Instead it offers the initial API affordances in the form of the links in the JSON body.

It is recommended to follow the “url” link values, Link or Location headers where applicable to retrieve resources. Instead of constructing your own URLs, to keep your client decoupled from implementation details.

GET https://YourHiasServer/hiashdi/v1

Response

Attributes
locations_url
required		 string
URL which points to the locations resource
/v1/locations
zones_url
required		 string
URL which points to the zones resource
/v1/zones
data_url
required		 string
URL which points to the statuses resource
/v1/data
types_url
required		 string
URL which points to the statuses resource
/v1/types
subscriptions_url
required		 string
URL which points to the subscriptions resource
/v1/subscriptions
CPU
required		 string
The current CPU usage of the HIAS Server (%)
98.8
Memory
required		 string
The current memory usage of the HIAS Server (%)
22.5
Diskspace
required		 string
The current diskspace usage of the HIAS Server (%)
15.1
Temperature
required		 string
The current temperature of the HIAS Server (°C)
99

 

Data

List Data

Retrieves a list of data that match different criteria by id, type, pattern matching (id) and/or those which match a query. Given data has to match all the criteria to be retrieved (i.e., the criteria is combined in a logical AND way). Note that pattern matching query parameters are incompatible (i.e. mutually exclusive) with their corresponding exact matching parameters, i.e. idPattern with id.

The response payload is an array containing one object per matching entity. Each entity follows the JSON entity representation format (described in "JSON Entity Representation" section of the FIWARE NGSI-V2 specification).

GET https://YourHiasServer/hiashdi/v1/data?id=00000000000000000000000&type=Statuses&idPattern=00000000.*&q=Application==00000000000000000000000&limit=20&offset=20&attrs=Status&orderBy=id&options=

Parameters Required Compliant
id A comma-separated list of elements. Retrieve entities whose ID matches one of the elements in the list. Incompatible with idPattern.
Example: 00000000000000000000000.		 String ☑
type A comma-separated list of elements. Retrieve entities whose type matches one of the elements in the list. Incompatible with typePattern.
Example: Statuses.		 String ☑ ☑
idPattern A correctly formated regular expression. Retrieve entities whose ID matches the regular expression. Incompatible with id.
Example: 00000000-.*.		 String ☑
q A query expression, composed of a list of statements separated by ;, i.e., q=statement1;statement2;statement3. See Simple Query Language specification of the FIWARE NGSI-V2 specification.
Example: Use==Application.		 String ☑
limit Limits the number of entities to be retrieved.
Example: 20.		 Number ☑
offset Establishes the offset from where entities are retrieved.
Example: 20.		 Number ☑
attrs Comma-separated list of attribute names whose data are to be included in the response. The attributes are retrieved in the order specified by this parameter. If this parameter is not included, the attributes are retrieved in arbitrary order. See "Filtering out attributes and metadata" section of the FIWARE NGSI-V2 specification.
Example: name.		 String ☑
orderBy Criteria for ordering results. See "Ordering Results" section of the FIWARE NGSI-V2 specification.
Example: temperature,!speed.		 String ☑
Options Options dictionary.
Possible values: count, unique.		 String ☑

Response

 

Create Data

The payload is an object representing the entity to be created. The object follows the JSON entity representation format (described in a "JSON Entity Representation" section of the FIWARE NGSI-V2 specification).

POST https://YourHiasServer/hiashdi/v1/data

Parameters Compliant
NA String ☑

Response:

 

Data by ID

Retrieve Data

The response is an object representing the data identified by the ID. The object follows the JSON entity representation format (described in "JSON Entity Representation" section of the FIWARE NGSI-V2 specification).

This operation must return one data element only.

GET https://YourHiasServer/hiashdi/v1/data/dataId?type=&attrs=Location%2Application

Parameters Required Compliant
dataId Id of the data to be retrieved. String ☑ ☑
type Entity type, to avoid ambiguity in case there are several entities with the same entity id. String ☑ ☑
attrs Comma-separated list of attribute names whose data must be included in the response. The attributes are retrieved in the order specified by this parameter. See "Filtering out attributes and metadata" section of the FIWARE NGSI-V2 specification. If this parameter is not included, the attributes are retrieved in arbitrary order, and all the attributes of the entity are included in the response.
Example: Location,Application		 String ☑
Response:

 

Retrieve Data Attributes

This request is similar to retreiving the whole data, however this one omits the id and type fields.

Just like the general request of getting an entire data, this operation must return only one entity element. If more than one entity with the same ID is found, an error message is returned, with the HTTP status code set to 409 Conflict.

GET https://YourHiasServer/hiashdi/v1/dataId/attrs?type=Application&attrs=network_location%2network_status&metadata=cpuUsage

Parameters Required Compliant
dataId Id of the entity to be retrieved. String ☑ ☑
type Data type, to avoid ambiguity in case there are several data elements with the same data id. String ☑ ☑
attrs Comma-separated list of attribute names whose data are to be included in the response. The attributes are retrieved in the order specified by this parameter. If this parameter is not included, the attributes are retrieved in arbitrary order, and all the attributes of the data are included in the response. See "Filtering out attributes and metadata" section of the FIWARE NGSI-V2 specification.
Example: network_location,network_status		 String ☑
Response:

 

Contributing

Asociación de Investigacion en Inteligencia Artificial Para la Leucemia Peter Moss encourages and welcomes code contributions, bug fixes and enhancements from the Github community.

Ways to contribute

The following are ways that you can contribute to this project:

Please read the CONTRIBUTING document for a contribution guide.

You can also join in with, or create, a discussion in our Github Discussions area.

Contributors

All contributors to this project are listed below.

 

Versioning

We use SemVer for versioning.

 

License

This project is licensed under the MIT License - see the LICENSE file for details.

 

Bugs/Issues

You use the repo issues to track bugs and general requests related to using this project. See CONTRIBUTING for more info on how to submit bugs, feature requests and proposals.