Deliverable 3.1.a: BIG IoT API Design

206 Pages·2017·2.78 MB·English

BIG IoT – Bridging the Interoperability Gap of the Internet of Things
Deliverable 3.1.a:
BIG IoT API Design - First Release
Version 1.0.1
Date: 31.12.2016
This project has received funding from the European Union’s Horizon 2020 research and
innovation program under grant agreement No 688038.
Deliverable 3.1.a – BIG IoT API Design D3.1.a
Responsible Person and Affiliation Siemens AG:
Andreas Ziller
Due Date / Delivery Date 31.12.2016
State Final Version
Reviewers Ernest Teniente (UPC)
Yong Wang (TUC)
Version 1.0
Confidentiality Public
© 2017 2
Deliverable 3.1.a – BIG IoT API Design D3.1.a
List of Authors
Organization Authors Main organizations’ contributions
Bosch Stefan Schmid, Denis Kramer Chapter2,3
Econais Dimitra Patroumpa, Costas Pipilas Section4.2
Siemens Andreas Ziller, Arne Bröring Chapter1,3,4,5
© 2017 3
Deliverable 3.1.a – BIG IoT API Design D3.1.a
Table of Contents
Abbreviations ....................................................................................................................... 6
1 Introduction .................................................................................................................. 7
1.1 Motivation ....................................................................................................................... 7
1.2 Relation to other Deliverables ......................................................................................... 8
2 BIG IoT API in context of the High-Level Architecture ................................................ 11
2.1 Core Concepts of the BIG IoT Architecture ..................................................................... 11
2.2 BIG IoT Architecture Overview ....................................................................................... 12
2.2.1 High-level Architecture Building Blocks .................................................................................... 13
2.3 Interfaces and Interactions ............................................................................................ 15
3 BIG IoT API Tutorial ..................................................................................................... 16
3.1 Introduction ................................................................................................................... 16
3.2 Setup .............................................................................................................................. 16
3.2.1 Preparation of your System ..................................................................................................... 17
3.2.2 Install and run Marketplace and eXchange ............................................................................... 18
3.2.3 Preperare and Run Demo......................................................................................................... 20
3.3 Registration on the Marketplace.................................................................................... 25
3.4 BIG IoT from a Provider's Perspective ............................................................................ 25
3.4.1 Authentication on the Marketplace ......................................................................................... 25
3.4.2 Create an Offering ................................................................................................................... 26
3.4.3 Registration of Offerings .......................................................................................................... 27
3.4.4 Implementing the access Callback ............................................................................................ 27
3.4.5 Activation of Offerings ............................................................................................................. 28
3.5 BIG IoT from a Consumer's Perspective ......................................................................... 29
3.5.1 Authentication on a BIG IoT Marketplace ................................................................................. 29
3.5.2 Creating a Query. ..................................................................................................................... 29
3.5.3 Querying the Marketplace ....................................................................................................... 30
3.5.4 Accessing Offerings. ................................................................................................................. 32
3.5.5 Continuous Access of Offerings ................................................................................................ 33
4 BIG IoT Web API .......................................................................................................... 35
4.1 Deployment Example ..................................................................................................... 36
4.2 Proxy Support for device-level Platforms ....................................................................... 40
© 2017 4
Deliverable 3.1.a – BIG IoT API Design D3.1.a
4.3 Blocking and Non-Blocking Operations .......................................................................... 41
4.4 Access Operation ........................................................................................................... 43
4.4.1 Specification ............................................................................................................................ 44
4.4.2 Dealing with Non-REST-like IoT platforms ................................................................................ 45
4.5 Feed Operation .............................................................................................................. 45
4.5.1 Synchronous vs. asynchronous feeds ....................................................................................... 45
4.5.2 Feed support in BIG IoT............................................................................................................ 47
4.5.3 Concepts for retrofitting Feed support ..................................................................................... 49
4.5.4 Lifecycle Management ............................................................................................................. 50
5 Conclusion & Outlook ................................................................................................. 53
Figures and Tables .............................................................................................................. 55
References .......................................................................................................................... 56
Appendix A UML Class Diagrams ........................................................................................ 57
Appendix B BIG IoT API Documentation ............................................................................. 61
© 2017 5
Deliverable 3.1.a – BIG IoT API Design D3.1.a
Abbreviations
Abbreviation Meaning
A1 Access Interface #1
API Advanced Programming Interface
BCN Barcelona (pilot)
BIG IoT Project title: Bridging the Interoperability Gap of the Internet of Things
DOA Description of Action
HTTP Hypertext Transfer Protocol
ID Identifier
IoT Internet of Things
IP Internet Protocol
ISO International Organization for Standardization
JAR Java Archive
JSON JavaScript Object Notation
MQTT Message Queue Telemetry Support
MS Milestone
NAT Network Address Translation
NG Northern Germany (pilot)
OD Offering Description
OGC Open Geospatial Consortium
P1 Programming Interface #1
P2 Programming Interface #2
P3 Programming Interface #1
PIE Piedmont (pilot)
RDF Resource Description Framework
REST Representational State Transfer
SDK Software Development Kit
SES Sensor Event Service
SOS Sensor Observation Service
SPARQL SPAQRL Protocol and RDF Query Language
SPS Sensor Planning Service
SWE Sensor Web Enablement
TCP Transmission Control Protocol
UI User Interface
URI Uniform Resource Identifier
URL Uniform Resource Locator
© 2017 6
Deliverable 3.1.a – BIG IoT API Design D3.1.a
1 Introduction
This chapter introduces to this deliverable, motivates the topic, and defines its scope.
1.1 Motivation
The idea of an Internet of Things is no more a futuristic vision, but indeed an increasing
commercial reality that reaches to various application domains ranging from quantified self
and smart home applications, over smarter cities and eHealth systems, to Industry 4.0. Doz-
ens of IoT platforms are upcoming. These include cloud solutions, such as Evrythng [1],
ThingWorx [2], Xively [3], or Yaler [4], but also on premise solutions such as Bosch’s IoT
Suite [5], as well as thematically or geographically focused platforms, such as the Smart Data
platform for the Piedmont region [6]. However, up to now, these IoT platforms failed to
form vibrant IoT ecosystems.
Currently, there is no vibrant collaborative IoT ecosystem, since the number of stakeholders
involved in IoT ecosystems (e.g., IoT platform providers, service and application providers) is
large, the market entry barriers are high, and the potential gain is low for a single stake-
holder. Providers of platforms and services require a simple, established way to offer access
to their resources. Marketplaces that enable providers to monetize access to the resources
offered by their platforms and services are not yet available. Once these marketplaces are
established, developers will be able to easily build IoT services and applications and build
their products around these. Revenue streams can then be shared across all contributing
entities (i.e., IoT platform and service providers). A key task of a marketplace is to provide
extended functionalities to enable the advertising, dynamic discovery, automated orches-
tration, and negotiation of services to facilitate their usage.
However, before such marketplaces can bring their effect, a serious market barrier needs to
be tackled: the missing interoperability. The fragmentation of the IoT and the lack of in-
teroperability prevent the emergence of broadly accepted IoT ecosystems [7]. A recent
McKinsey study [8] estimates that a 40% share of the potential economic value of the IoT
directly depends on interoperability between IoT platforms. Today, we are dealing with var-
ious vertically oriented and mostly closed systems. Architectures for IoT are built on
heterogeneous standards (e.g., IETF CoAP [9], OASIS MQTT [10], OMA LWM2M [11], OGC
SWE [12], or OneM2M [13]) or even proprietary interfaces. As a result, most existing and
emerging IoT platforms offer heterogeneous ways for accessing IoT resources.
© 2017 7
Deliverable 3.1.a – BIG IoT API Design D3.1.a
This causes interoperability problems when overarching, cross-platform, and cross-domain
applications are to be built, and eventually prevents the emergence of vibrant IoT ecosys-
tems. Additionally, it leads to barriers for business opportunities, especially for small
innovative enterprises, which cannot afford to offer their solution across multiple platforms.
They can only provide applications and services for a small number of platforms, e.g., a traf-
fic information application for an IoT platform of a specific city. This lack of interoperability
results in lost business opportunities and prevents innovative business ideas.
In order to address these shortcomings in today's IoT landscape, the BIG IoT project has de-
veloped an architecture as a foundation for building IoT ecosystems (see D2.4). It
overcomes the above described hurdles through (1) a common API, (2) semantic descrip-
tions of resources and services, as well as (3) a marketplace as a nucleus of the ecosystem.
This will allow new services by combining data from multiple platforms (e.g., parking infor-
mation from various smart city platforms). In addition, platforms from multiple domains
(e.g. home and city) and regions will be combined, such that applications can utilize all rele-
vant information and work seamlessly across regions (e.g. the same smart parking
application works on top of a smart city platform in Berlin, in Barcelona and in London).
The scope of this document is the specification of the BIG IoT API. This BIG IoT API can be
seen from two complementary perspectives, as (1) a Programming API implemented as li-
braries (libs) of an SDK and (2) a Web API. Both perspectives are covered in this document.
The Programming API is provided to developers in order to facilitate the implementation of
applications or the provision of platforms and services. The Web API defines protocols and
encodings for actual message exchange to implement the various interactions and work-
flows designed. Thereby, the Programming API abstracts from the underlying
communication protocols defined in the Web API.
Parts of this deliverable (mainly section 3) will be used as online documentation, which will
be accessible to developers. For an easy understanding, those parts are written in a tutorial-
style. This documentation will facilitate the onboarding of external developers joining
through an open call and it will generally help to grow the BIG IoT ecosystem.
1.2 Relation to other Deliverables
The tasks of WP3 and WP4 are highly interrelated, however, their deliverables have each
their own, clear responsibilities. Figure 1 follows the general BIG IoT architecture descrip-
tion in D2.4 and illustrates at hand of this architecture the scope of each of the different
deliverables of the tasks 3.1, 3.2, 4.1, 4.2, and 4.3.
© 2017 8
Deliverable 3.1.a – BIG IoT API Design D3.1.a
Figure 1 Relation of deliverables
D3.1 covers the description of the BIG IoT API. This entails a specification of the Web API
(e.g., interaction model, and encodings) as well as description of the programmatic API that
is implemented as part of consumer and provider lib of the SDK.
D4.1 describes the architecture of the BIG IoT Marketplace. This includes the general design,
the workflows of interactions, the GraphQL-based API of the marketplace, as well as the
user interface of the portal to utilize the marketplace. Also contained in this deliverable is a
description on how to map between the GraphQL API of the marketplace frontend and its
SPARQL based triple store backend.
D3.2 describes the model and schema of the core semantic model of BIG IoT. This semantic
model is used as a basis for (1) the Offering description to define the capabilities of offerings
provided by IoT platforms or services, and (2) the underlying data model of the BIG IoT Mar-
ketplace.
© 2017 9
Deliverable 3.1.a – BIG IoT API Design D3.1.a
D4.2 builds up on the core semantic model of D3.2 and defines the application domain
model, which specifies a vocabulary of terms that can be used in Offering descriptions, and
in the triple store of the marketplace.
D4.3 addresses the orchestration and composition of the offerings of BIG IoT providers (i.e.,
platforms or services). A composition of offerings can be specified by defining a Recipe. The
semantic model and examples of such recipes is the scope of this deliverable.
© 2017 10