Bachelor Degree Project Design Abstraction of IoT REST APIs

(1)

Authors:

Adell Tatrous,

Rasmus Svensson

Supervisor:

Francis Palma

Semester:

VT 2020

Subject:

Computer Science

Bachelor Degree Project

Design Abstraction of IoT REST

APIs

(2)

Abstract

Smart devices (or things) in the realm of IoT (Internet of Things) talk to each other and transfer data over the Internet. IoT vendors provide APIs for their clients to send data to the gateways and application servers. However, there is a lack of guidelines on how a vendor would design its API and resource URIs (Uniform Re-source Identifiers). A generic design solution – design patterns – would make the API design and development easier for the vendors. Design patterns are reusable solutions to recurring problems and provide improved reusability and understand-ability. Currently, there are no design patterns for URIs of IoT APIs that IoT vendors can use. In this paper, we analyzed more than 1,300 URIs from 13 IoT APIs includ-ing IBM Watson and Microsoft Azure, and proposed eight novel design patterns for URIs of IoT APIs. We analyzed one dataset divided into two subsets: (1) analysis set with 70% of all our URIs to define design patterns for URIs of IoT APIs and (2) validation set with the remaining 30% of the URIs to verify the prevalence of the de-fined design patterns. We could map 84% of our validation set to the dede-fined design patterns, i.e., design patterns are prevalent in the IoT domain.

(3)

Preface

(4)

1 Introduction

In this chapter, some background information about essential terms for our report will be introduced. Then, other work that has been done for solving design issues for APIs will be presented. Furthermore, the goal of the project will be stated. Some objectives that has to be fulfilled in order to solve this problem will be defined. Moreover, the scope and limitations for defining the design patterns in this paper will be included as well as the target group that this study will be interested to. Lastly, a short overview for the rest of this paper will be presented.

1.1 Background

Design patterns are reusable solutions to recurring design problems in software engineer-ing [1]. Among numerous benefits, design patterns make the systems easier to understand and maintain. Design patterns work as a common language for designers and developers, which is essential to build a system efficiently.

Design patterns are also useful in designing and developing Web services, e.g., REST-ful APIs. RESTREST-ful Web services are designed and developed based on the resources, where resources are identified using URIs (Uniform Resource Identifiers) [2]. The suc-cess of a RESTful Web service depends on the ease with which its clients can adopt the provided API, which includes understandability. Essentially, this would benefit the reusability of the API, which is why design patterns were proposed originally.

Researchers proposed design patterns for RESTful Web services [3]. However, those design patterns focus more on ensuring the RESTful-ness of the APIs, i.e., suggest guide-lines to design APIs that make the APIs truly RESTful. Moreover, the design patterns for REST APIs proposed in the literature are micro-level patterns, e.g., how the versioning should be done, the endpoint should be designed, a service contract can be made uniform, and so on. Thus, design patterns at the URI-level are still missing. However, there are some contributions to defining design patterns for REST APIs [4].

In the era of the Web, an emerging domain called IoT (Internet of Things) relies on smart devices or things that communicate over the Internet and talk to each other using an application layer protocol like HTTP or MQTT. As the IoT paradigm is heavily things-oriented, the design guidelines for URIs should focus more on IoT-centric architecture [5]. To the best of our knowledge, there are no defined design patterns for IoT APIs. This is the first study that thoroughly analyzes IoT APIs and proposes relevant design patterns based on a subset of existing URIs of IoT APIs. The prospective IoT vendors can benefit from this by designing and developing their APIs based on our suggested design patterns, which would increase the reusability and understandability of their IoT APIs.

1.2 Related Work

Researchers proposed design patterns for REST (REpresentational State Transfer) APIs (Application Programming Interfaces) [4, 6]. For example, Abbas and Ojo [4] proposed a set of eight design patterns by consolidating existing URI design rules and then ab-stracting the rules into a set of URI design patterns specifications. However, the proposed design patterns are domain-specific, i.e., geospatial data that describe information related to locations on Earth. For this, the authors used the vocabulary of inter-linked datasets and best practices for URI construction.

(6)

software-defined networking. However, the goal of this was to ensure that APIs conform to REST constraints [8]. Besides, the proposed design patterns are not applicable in other domains, i.e., only for the network applications.

Other studies to improve the URI design include Wilkinson et al. [9], where the au-thors proposed the SADI approach (Semantic Automated Discovery and Integration) that consists of a set of recommendations on how the services should be implemented and described in order to achieve high interoperability. More specifically, SADI proposed a set of conventions and best-practices for developing APIs in the bioinformatics domain. Some books discussed the best practices for URI design [3, 10]. However, they defined best practices in the forms of design rules to help designers in designing readable and understandable URIs at the micro-level, i.e., how the version number should be provided, the pagination should be used, name the resources to avoid confusions. Yet, design pat-terns at the URI-level are still missing, which would work as a common language for the designers.

McEwen and Cassimally [11] described the design of the Internet of Things (IoT) at the application level that combines hardware and software.

Our study is the first to provide a set of usable design patterns for the URIs of IoT APIs regardless of the domain. Moreover, our design patterns can work as a common language among API designers.

1.3 Problem Formulation

The fact that there are no design guidelines and patterns for URIs of IoT APIs causes API designers to design the URIs based on their experiences, understanding and judg-ment. Due to this, the URIs in IoT do not have any uniform design, which hinders their understandability and reusability.

The goal of this project is to observe, derive and abstract already existing patterns in some IoT REST APIs, i.e., we do not suggest any new design patterns but rather, based on existing API providers, we extract a standard for URIs of IoT REST APIs and encourage prospective IoT vendors to start using this standard. The resulting design patterns can be used by designers as a guide when designing new IoT APIs.

1.4 Motivation

The continuously increasing number of IoT-devices in our society makes higher demands on the development of high-quality APIs and several companies are, therefore, developing their APIs for their purposes without following a design standard. The differences, e.g., the heterogeneity of the IoT domain [12], can lead to less understandability and reusabil-ity when it comes to the communication between different devices. Therefore, it is of high interest to analyze and compare the APIs to each other in order to come up with a design standard that will ensure high-quality REST APIs [4]. By having a design standard, APIs can be created using its pre-defined guidelines, which will make the communication be-tween the developed APIs and devices more reliable and also increase understandability and reusability, since they will only have to adapt to one standard.

1.5 Objectives

(7)

O1 Thorough manual analysis of IoT APIs.

O2 Documenting the observations and information found about the in-cluded URIs.

O3 Formally define the design patterns, through design abstraction, using a pattern template (as used by GoF design patterns [1]).

O4 Perform a validation process to see the prevalence of the defined de-sign patterns in unseen URIs.

O5 Visualize the patterns frequency results.

Table 1.1: Objectives of This Study.

1.6 Scope and Limitation

When analyzing the IoT APIs, we will not install nor test any of them. Instead, we will only go through the documentation to find out the structures of the URIs and how they are supposed to work. This, however, might cause a problem if the documentation is poor or vague. Since our understanding of all the nodes involved in the URI, the request method used and the purpose of the URI are essential when it comes to affecting the quality of our observations.

1.7 Target Group

The target group for this study is API designers and especially those who design IoT APIs, since this is focusing on design patterns for IoT APIs more than APIs in general. The results of this paper can be helpful for IoT API designers when creating new IoT APIs, i.e., informing IoT API designers of which design patterns that are most used among the existing IoT APIs.

1.8 Outline

The rest of this paper is organized as follows:

(8)

2 Methodology

In this chapter, we describe our methodology for defining design patterns for URIs of IoT APIs. Figure 2.1 shows the various steps starting from the collection of APIs docu-mentation, analysis of URIs, definition of design patterns, and finally, manually validate newly defined design patterns on a set of unseen URIs. The subsequent chapters present our patterns defining strategy, the template that we used to present the design patterns, the validation strategy we have used on the defined patterns, and the possible threats to validity and how we minimize them.

URIs Documentation Data Separation Validation Data Analysis Data URI Validation URI Analysis Observations Documentation Conclusion Extraction Design Patterns Definition Scheme Authority Base Main Query

30% 70% Each URI Each API Each URI

Figure 2.1: Our Methodology of Defining Design Patterns.

2.1 Design Patterns Defining Strategy

We followed several steps to define design patterns, as depicted in Figure 2.1. The steps undertaken include the following:

1. We manually gather more than 1,300 URIs (regardless of the HTTP methods) from 13 IoT REST APIs, as listed in Table 2.1. To avoid biasing the outcome of the research, the URIs are gathered from APIs with various sizes and provided by dif-ferent vendors. Many of these APIs are provided by well known companies like Microsoft, Cisco and IBM. This will increase our trust with the found URI designs. This is important since we are not going to reason about the found patterns and why they are chosen by the involved API designers.

2. We randomly split all the collected URIs into two sets: (1) the analysis set with 70% of all URIs to be used for defining design patterns and (2) the validation set with the remaining 30% of the URIs to be used for validating the defined design patterns. We perform this split for each IoT API. Table 2.1 shows the number of URIs in the analysis and validation set.

(9)

3986 [13], a URI can be divided into five sections:

Scheme://Authority/Path?Query#Fragment. To be able to analyze further, we extended this structure by dividing the Path section into Base and Main sections, and disregard the Fragment section since it is not found in any URIs. Thus, the resulting URI sections will instead be

Scheme://Authority/Base/Main?Query.

4. Based on the newly defined URI structure, we analyze the analysis set for each API by documenting observations in each section.

5. Observations gathered for all the analysis set are grouped, and then, we determine obvious, common, and repeated patterns among all APIs. This process is done by manually comparing the behaviours that we have noticed and documented in each API.

6. Design patterns are concretely defined based on the findings of the previous step. 7. Finally, we use the validation set to validate the patterns, i.e., to find the prevalence

of newly defined design patterns among the unseen validation set. For this, we manually map each URI in the validation set to see if they fit any newly defined patterns, and if yes, to which pattern(s).

IoT APIs APIs Documentation URLs #URIs in Analysis #URIs in Validation Total Ambrosus Gateway https://ambrosus.docs.apiary.io/# 10 4 14 Cisco IPICS https://www.cisco.com/c/en/us/td/d

ocs/interoperability_systems/c_ipi cs/461/api/guide/api461/restfunc.h tml

4 1 5

Clear Blade https://docs.clearblade.com/v/4/st atic/api/index.html

116 50 166

Cube Sensors https://my.cubesensors.com/docs 3 1 4 Droplit.io https://docs.droplit.io/ 142 61 203 IBM Watson IoT https://docs.internetofthings.ibmc

loud.com/apis/swagger/index.html

189 80 269

Losant https://docs.losant.com/rest- api/o verview/

152 65 217

Microsoft Azure https://docs.microsoft.com/en- us/r est/api/iothub/ 124 52 176 Particle https://docs.particle.io/reference /device-cloud/api/ 77 33 110 Sonos https://developer.sonos.com/refere nce/ 46 20 66 thethings.iO https://developers.thethings.io/re ference 23 10 33

The Things Network https://www.thethingsnetwork.org/d ocs/applications/manager/api.html 8 4 12 Toon https://developer.toon.eu/toonapi/ apis 18 8 26 Total 912 389 1,301

Table 2.1: The List of 13 IoT APIs Analyzed in this Study.

2.2 Template for Design Patterns Definition

(10)

• Name: States the chosen name of the design pattern.

• Description: Provides some background about when, why, and how this pattern could be useful.

• Affected Sections: Mentions the sections that this pattern applies to.

• Forms: Enumerates the variants that this pattern might take in a URI, i.e., the different positions that nodes and variables might take in the URI.

• Sources: Mentions the APIs that this pattern was found in.

• Examples: Enumerates some realistic examples from the studied APIs.

2.3 Design Patterns Validation Strategy

We perform the validation process with our validation set, which is 30% of our initially gathered data, i.e., 389 URIs, as stated in Table 2.1. To avoid the bias, the validation set was not exposed until all the URIs in the analysis set are analyzed and the definition of design patterns is done. The goal of the validation is to see if our newly defined design patterns are meaningful, i.e., if we can map each URI from the unseen validation set to certain design pattern(s) that are defined based on the known analysis set.

We follow an iterative and manual validation using the first-past-the-post technique [14] by the maximum voting system. In particular, for a URI in the validation set, if the two authors agree on a design pattern, the URI is assigned to that design pattern class. In the case of a tie, the supervisor gets involved.

2.4 Threats to Validity

The main threat to the validity of our proposed design patterns and the validation process of them concerns their external validity, i.e., the possibility to generalize our defined design patterns and the validation results. In this paper, we minimize threats to external validityby analyzing more than 1,300 URIs from 13 IoT APIs. Moreover, not to bias the outcome, we made sure that we randomly split the data into a 70%-30% ratio for each API.

For internal validity, the defined design patterns depend on the selected APIs and on how the data got split. To minimize the threat to the internal validity, we performed our validation process and tried to map each URI in the validation set to see whether unseen URIs can be matched to our defined design patterns. We performed the same on the analysis set to further confirm the findings from the validation set.

(11)

3 Results

In this chapter, all the observations found for each URI section will be introduced. Be-sides, the definitions and terms to structure this study will be presented. Furthermore, we introduce the design patterns and later validate the validation set.

3.1 Our Observations on URI Sections

To structure our findings from the study on our analysis set and defining the design pat-terns, we have grouped all the different types of nodes involved in our results, each ac-companied by a definition, in Table 3.1.

For the Scheme section that incorporates the protocol used in the URI, all analyzed APIs have one of two following variants:

• HTTP in Cube Sensors and The Things Network;

• HTTPS in Ambrosus Gateway, Cisco IPICS, Clear Blade, Droplit.io, IBM Watson, Losant, Microsoft Azure, Particle, Sonos, thethings.iO, and Toon;

The Authority section incorporates the host and, rarely, the port, i.e., host:port used in the URI. The Authority section also includes all the possible variables required to redirect the URIs at specific services, areas, organizations, and so on. Two variants are found among all the analyzed APIs:

• Static: the Authority section has the same string for all users of the API, e.g.,

/hermes.ambrosus- test.com in

https://hermes.ambrosus-test.com in Ambrosus Gateway and /platform.clearblade.com in

https://platform.clearblade.comin Clear Blade.

• Dynamic: the Authority section consists of a variable constructed for each user, e.g., ‘servername’ inhttps://servername/ipics_server/handsets ervice in Cisco IPICS represents a qualified host name provided by the user. Alternatively, the Authority section includes a variable in it that is placed at the beginning of the section, e.g., ‘orgId’ in https://{orgId}.internetof

things.ibmcloud.com in IBM Watson that represents a 6-character string

ID to identify the organization within this API. Also, ‘fully-qualified-iothubname’

in https://fully-qualified-iothubname.azure-devices.net

in Microsoft Azure represents a unique name string that is provided by the user and follows the API standards. The ‘region’ inhttp://<region>.thethin gs.network:8084in The Things Network represents the area code string that users provide depending on the geographical area of their application.

The Base section usually incorporates the version of the API, among other Access Node(s)(as defined in Table 3.1), that are used in the majority of the URIs provided by an API. The Base section, in contrast to the previous sections, does not have to be included in the URI, e.g., as in Ambrosus Gateway, Microsoft Azure, The Things Network, and Losant. But if it does, it can take the whole section as Access Node(s) only. For example,

the/ipics_server/handsetservice in all URIs provided by Cisco IPICS, and

/adminor/codeadminin some of the URIs provided by Clear Blade.

(12)

Name Description

Access Node A node that is used only to direct the following parts of the URI to a certain section of the API, i.e., it is not a resource or data that could be fetched.

Indicative Node A node that represents an order, query or action to be taken on a certain resource to apply this action or know a specific infor-mation about this resource, e.g., filtering the results of a request made on a certain resource. We can think of it as an endpoint that triggers a function. It is usually a conventional word such as ‘info’, ‘create’, ‘last’, ‘status’, etc. Indicative Nodes can be divided into three categories: Action Nodes, Filtering Nodes, and Informational Nodes.

Parent Node A node that usually represents a category, a resource that in-cludes resources or an object; in the API and the URI this node exists in a hierarchy. Here, we tend to mention only the end of the hierarchy. For instance, when a resource is accessed by these ways /parentnode1/{var1}.../parentnod

eN/{varN} or /parentnode1/{var1}.../paren

tnodeN we only mention /parentnodeN/{varN} or

/parentnodeN.

Action Node A node used to trigger a specific function or apply classic CRUD functionalities on a resource, using any HTTP request method. In most cases, these nodes take a form of an order to perform an action e.g. ‘create’, ‘clone’, ‘upload’, or ‘con-sume’.

Filtering Node A node used to target a specific group or state of the requested resources.

Informational Node A node used to get information about metadata for a single or multiple resources. These metadata cannot be directly modi-fied nor accessible through the resource.

Table 3.1: The Definitions of Node Types.

the whole Base section, e.g., /v1 in all URIs of Cube Sensors,/v1 in most URIs of Particle, and/v2in all URIs of thethings.iO. The Access Node(s) and the version of the API could be mentioned together to represent this section. The version could be:

• A single node after the Access Node(s), e.g., /api/v0002 in all URIs of IBM Watson,/control/api/v1in most URIs of Sonos and/toon/v3in all URIs of Toon;

• A single node before the Access Node(s), e.g.,/v0/apiin most URIs of Droplit.io; • Multiple nodes after the Access Node(s), e.g.,/admin/v/4,/codeadmin/v/2,

/api/v/1,/api/v/2,/api/v/3or/api/v/4in some URIs of ClearBlade;

(13)

its purpose. The Indicative Nodes presented in Table 3.2 are found in URIs to apply the CRUD functionalities or other processes on resources and their metadata. These nodes could be placed inside this section in various ways. For example, an Indicative Node can be placed either before, after, or in the middle of a chain of Parent Node(s), which are described in Table 3.1, depending on the purpose of this node. It is worth mentioning that most of the URIs studied have a conventional structure that does not have any extra nodes apart from the Parent Node(s).

IoT APIs / Indicative Node Action Node Filtering Node Informational Node Ambrosus Gateway /info,/create,/listand/modify. - /nodeinfo.

Cisco IPICS /join,/uploaddata, and/leave. - /userdirectory. Clear Blade /putpass,/regensystemsecret,/publi

sh,/reg,/auth,/anon,/checkauth,/exe cuteand/logout.

/ h i s t o ry

and/faile d.

/count,/connectioncou

nt,/logs,/userinfoand

/definitions.

Cube Sensors - - /current.

Droplit.io /create,/consume,/undelete,/react

ivate,/activate,/start,/exportand

/disable.

- /state.

IBM Watson IoT /add,/remove,/cancel,/download,/mul tiple,/requestand/restore.

/draft. /edgestatus,/connectio

n,/data-trafficand/ser vice-status.

Losant /clone,/export,/search,/import,/del

ete,/query,/truncate,/setConnection

State,/mqttPublishMessage,/release,

/bootstrap,/upload,/changePassword,

/disableTwoFactorAuth,/disconnectG

ithub,/disconnectTwitter,/refreshTo

ken,/transferResources,/verify-emai

land/execute.

- /archiveData,/fullDat

aTablesArchive,/paylo

adCounts,/state,/fullE

ventsArchive,/mqttSub

scriptionStream,/linke

dResources,/statsand/l ogs.

Microsoft Azure /applyConfigurationContent,/testQue ries,/abandon,/cancel,/create,/query,

/checkNameAvailability,/exportDevic

es,/importDevices,/verifyand/search.

- /statistics.

Particle /ping,/device_claims,/password-rese t,/testand/release.

- /current,/last,/metad

ata,/status,/data_usa

geand/impact. Sonos /access,/subscription,/relative,/mut

e,/match,/lineIn,/play,/pause,/seek,

/skipToNextTrack,/skipToPreviousTra

ck,/togglePlayPause,/join,/joinOrC

reate,/loadCloudQueue,/skipToItem,

/loadStreamUrl,/refreshCloudQueue,

/suspendand/getPlaylist.

- /playbackMetadata.

thethings.iO - - /latest.

The Things Network - -

-Toon /states. - /flowsand/data.

Table 3.2: The List of All Found Indicative Nodes in Analysis set URIs.

(14)

all the URIs from all APIs follow the same structure?key1=value1&key2=value2 &...rather than other forms like?value1&value2&...or?value1,value2,.. ., etc.

3.2 Design Patterns

We present eight design patterns that are abstracted from the URIs from our analysis set. For each design pattern, we also represent them graphically 1 _{to show the relationships}

among the various constituents of the pattern, i.e., how they are associated to form a design pattern. We present these graphical representation as a vertically descended set of layers where each layer represents a URI section, starting with the Authority section. These figures, however, are meant to be a complement to the ‘Forms’ row in each table representing the design pattern.

Tables 3.3 to 3.10 describe our eight design patterns using the template presented in Chapter 2.2. The tables also include the graphical representation of each design pattern.

In summary, among our eight defined design patterns: one is related to the Author-ity section, one is related to both Base and Query sections, five are related to the Mainsection, and one for the Query section.

3.3 Design Patterns Validation

We performed the validation process on the validation set with 389 URIs, i.e., 30% of all collected URIs from 13 IoT APIs. Table 3.11 shows the distribution of URI counts over the design patterns for each API from the validation set. The results show that the majority of the URIs follow the Versionized API and Early Directed URI patterns regardless of the APIs, which is 75% and 31%, respectively. The Expressive Request pattern is also moderately common among the APIs. Although ‘me’ Accessible Resources, Metadata Retrievabilityand Versionized Resources are less frequent among the APIs, this might be subject to the gathered URIs, and thus, the validation set. However, at the beginning of the pattern defining process, we split the dataset randomly to avoid biasing the pattern frequency both in validation and analysis sets.

In conclusion, we were able to map 84% of the URIs (325 out of 389 URIs) to at least one defined design pattern. This suggests that the IoT design patterns are indeed prevalent.

(15)

Name Early Directed URI (ED_URI)

Description To direct the requested URI at a specific or unique subsection of the API, such as an organization ID, an area code or a cus-tom server name, use a variable at the beginning of the Au-thoritysection followed by a period.

Affected Sections Authoritysection.

Forms 1.Scheme://{variable}.../Base/Main?Query

Sources IBM Watson IoT, The Things Network and Microsoft Azure.

Examples 1.https://myiothub.azure-devices.net/jobs 2.http://eu.thethings.network:8084/appli cations Figure Keys Scheme section String variable Rest of the Authority section Base section Main section Query section :// / / ? .

(16)

Name Expressive Request (ER)

Description To perform the classic CRUD functionalities or trigger a spe-cific function on a resource, add an Action Node in the Main section.

Affected Sections Mainsection.

Forms 1.Scheme://Authority/Base/../ActionNode?Q

uery

2.Scheme://Authority/Base/../ParentNode/A

ctionNode/{variable}?Query

Sources Ambrosus Gateway, Cisco IPICS, thethings.iO, Particle, Clear Blade, Losant, Droplit.io, IBM Watson IoT, Microsoft Azure, SONOS and Toon.

Examples 1.https://platform.clearblade.com/admin/ checkauth 2.https://ioe.droplit.io/v0/api/zones/12 3/behaviors/456/start 3.https://hermes.ambrosus-test.com/accou nt2/modify/123 Figure Keys Scheme section Authority section Base section Rest of the Main section Query section Action node 1 2 Parent node String variable N Number to follow the forms of the pattern across the different sections :// / / / / / / ?

(17)

Name ‘me’ Accessible Resources (MAR)

Description To point at the currently authenticated user when requesting resources or performing actions that this user has access to, use a ’me’ node at the beginning of the Main section.

Forms 1.Scheme://Authority/Base/me/..?Query

Sources thethings.iO and Losant.

Examples 1.https://api.losant.com/me/refreshToken 2.https://api.thethings.io/v2/me/resourc es/123 Figure Keys Scheme section Authority section Base section Rest of the Main section Query section ‘me’ node :// / / / ?

(18)

Name Metadata Retrievability (MR)

Description To read information, mostly using the GET method, about metadata for a single or multiple resources such as: count, state, status or other data that cannot be directly modified nor accessible through a resource, the URI can have a meaningful Informational Nodeat the end of the Main section.

Forms 1.Scheme://Authority/Base/../Informationa

lNode?Query

Sources Ambrosus Gateway, Cisco IPICS, Cube Sensors, thethings.iO, Particle, Clear Blade, Losant, Droplit.io, IBM Watson IoT, Mi-crosoft Azure, SONOS and Toon.

Examples 1.https://platform.clearblade.com/admin/ user/123/roles/count 2.https://api.particle.io/v1/sims/123/st atus Figure Keys Scheme section Authority section Base section Rest of the Main section Query section Informational node :// / / / ?

(19)

Name Proactive Filtering (PF)

Description To target a specific group or state of the requested resource without relying on a dedicated query parameter, use a Filtering Nodein the Main section.

Forms 1.Scheme://Authority/Base/../FilteringNod

e/ParentNode/..?Query

2.Scheme://Authority/Base/../ParentNode/F

ilteringNode/..?Query

Sources Clear Blade and IBM Watson IoT.

Examples 1.https://123456.internetofthings.ibmclo ud.com/api/v0002/draft/schemas 2.https://platform.clearblade.com/codead min/failed Figure Keys Scheme section Authority section Base section Rest of the Main section Query section Filtering node 1 2 Parent node N Number to follow the forms of the pattern across the different sections :// / / / / / / / / ?

(20)

Name Querified Authentication (QA)

Description To provide the authentication string of the user in the URI when using the GET method, instead of providing it in the header or the body when using other methods, use a dedicated query parameter.

Affected Sections Querysection.

Forms 1.Scheme://Authority/Base/Main/?{authenti

cation- key}={authentication- string- valu e}.. Sources Particle. Examples 1.https://api.particle.io/v1/events/123?a ccess_token=456789

Figure Keys

Scheme section

Authority section

Base section

Main section

Query-Key to represent

the authentication string

Query-Value of the

authentication string

://

/

?

=

(21)

Name Versionized API (V_API)

Description To add the version of the API in a selected single section to differentiate between the updated types of the API, use either a dedicated version number in the Base section, that could be put in different places, or a date-string as a query parameter. Affected Sections Baseand Query sections.

Forms 1.Scheme://Authority/v{number}/Main?Query 2.Scheme://Authority/AccessNode(s)/v{numb er}/Main?Query 3.Scheme://Authority//AccessNode(s)/v/{nu mber}/Main?Query 4.Scheme://Authority/v{number}/AccessNode (s)/Main?Query 5. Scheme://Authority/Base/Main?{version-key}={version-data-value}..

Sources Cube Sensors, thethings.iO, Particle, Clear Blade, Droplit.io, IBM Watson IoT, Microsoft Azure, SONOS and Toon.

Examples 1.http://api.cubesensors.com/v1/devices 2.https://123456.internetofthings.ibmclo ud.com/api/v0002/device 3.https://api.ws.sonos.com/control/api/v 1/groups/123 4.https://platform.clearblade.com/api/v/ 3/code 5.https://ioe.droplit.io/v0/api/clients 6.https://myiothub.azure-devices.net/con figurations/123?api-version=2020-03-13 Figure Keys Scheme section Authority section Base section Main section Query section 1.1 1.2 1.3 1.4 2 1 2 ‘v’ string to represent the version Number of the version Access node Query-Key to represent the version Query-Value to of the version N Number to follow the forms of the pattern across the different sections :// / / / / / / ? =

(22)

Name Versionized Resources (VR)

Description To add the version of a resource in the URI to differentiate be-tween the various types of updated functionalities that the API provides on the requested resource, use a dedicated number in the same resource node or as a separate node.

Forms 1.Scheme://Authority/Base/../ParentNode

{number}/..?Query

2.Scheme://Authority/Base/../ParentNode/v

{number}/..?Query

Sources Ambrosus Gateway and Microsoft Azure.

Examples 1.https://hermes.ambrosus-test.com/accou nt2/info/accountAddress 2.https://myiothub.azure-devices.net/job s/v2/123 Figure Keys Scheme section Authority section Base section Rest of the Main section Query section ‘v’ string to represent the version 1 2 Parent node N Number to follow the forms of the_{pattern across the different sections} Number of the version :// / / / / / / / ?

(23)

IoT APIs / Patterns ED_URI ER MAR MR PF QA V_API VR Ambrosus Gateway 0 4 0 0 0 0 0 4 Cisco IPICS 0 0 0 0 0 0 0 0 Clear Blade 0 5 0 1 2 0 29 0 Cube Sensors 0 0 0 1 0 0 1 0 Droplit.io 0 10 0 0 0 0 61 0

IBM Watson IoT 80 0 0 0 19 0 80 0

Losant 0 4 4 4 0 0 0 0

Microsoft Azure 36 5 0 1 0 0 52 4

Particle 0 1 0 1 0 7 32 0

Sonos 0 11 0 2 0 0 19 0

thethings.iO 0 5 5 1 0 0 10 0

The Things Network 4 0 0 0 0 0 0 0

Toon 0 1 0 1 0 0 8 0

Total 120 46 9 12 21 7 292 9

Total in Percentage 31% 12% 2% 3% 5% 2% 75% 2%

Table 3.11: Patterns Frequency in Validation Set for All Studied URIs.

4 Analysis

In Chapter 3, we mapped each URI in the validation set to see whether unseen URIs can be matched to our defined design patterns. In this chapter, we further generalize the outcome from the validation set by tagging each URI from the analysis set to at least one design pattern. Table 4.1 shows the distribution of URI counts over the design patterns for each API from the analysis set. We found similar pattern usage frequency regardless of the API, i.e., we still have Early Directed URI and Versionized API as the most common pattern and Expressive Request pattern as the third most frequent design pattern applied in the design of IoT REST APIs.

(24)

IoT APIs / Patterns ED_URI ER MAR MR PF QA V_API VR Ambrosus Gateway 0 6 0 1 0 0 0 6 Cisco IPICS 0 3 0 1 0 0 0 0 Clear Blade 0 12 0 9 5 0 55 0 Cube Sensors 0 0 0 1 0 0 3 0 Droplit.io 0 11 0 1 0 0 142 0

IBM Watson IoT 189 10 0 5 41 0 189 0

Losant 0 25 10 12 0 0 0 0

Microsoft Azure 78 22 0 2 0 0 124 5

Particle 0 5 0 7 0 23 72 0

Sonos 0 30 0 1 0 0 45 0

thethings.iO 0 1 9 1 0 0 23 0

The Things Network 8 0 0 0 0 0 0 0

Toon 0 1 0 8 0 0 18 0

Total 275 126 19 49 46 23 671 11

Total in Percentage 30% 14% 2% 5% 5% 3% 74% 1%

Table 4.1: Patterns Frequency in Analysis Set for All Studied URIs.

Patterns Total Number of URIs Total in Percentage

Early Directed URI 395 30%

Expressive Request 172 13%

‘me’ Accessible Resources 28 2%

Metadata Retrievability 61 5%

Proactive Filtering 67 5%

Querified Authentication 30 2%

Versionized API 963 74%

Versionized Resources 20 2%

Table 4.2: Patterns Frequency in Analysis and Validation sets Combined for All Studied URIs. 0 100 200 300 400 500 600 700 800 Early Directed URI

Versionized API Metadata Retrievability Expressive Request Proactive Filtering ‘me’ Accessible Resources Versionized Resources Querified Authentication

Patterns Frequency in Analysis and Validation Sets

Analysis Set Validation Set

(25)

0 1 2 3 4 5 6 7 Early Directed URI Versionized API Metadata Retrievability Expressive Request Proactive Filtering ‘me’ Accessible Resources Versionized Resources Querified Authentication

Patterns Frequency in Ambrosus Gateway API

Figure 4.2: Patterns Frequency in Ambrosus Gateway API.

0 0.5 1 1.5 2 2.5 3 3.5 Early Directed URI Versionized API Metadata Retrievability Expressive Request Proactive Filtering ‘me’ Accessible Resources Versionized Resources Querified Authentication

Patterns Frequency in Cisco IPICS API

Figure 4.3: Patterns Frequency in Cisco IPICS API.

0 10 20 30 40 50 60 Early Directed URI Versionized API Metadata Retrievability Expressive Request Proactive Filtering ‘me’ Accessible Resources Versionized Resources Querified Authentication

Patterns Frequency in Clear Blade API

(26)

0 0.5 1 1.5 2 2.5 3 3.5 Early Directed URI Versionized API Metadata Retrievability Expressive Request Proactive Filtering ‘me’ Accessible Resources Versionized Resources Querified Authentication Patterns Frequency in Cube Sensors API

Figure 4.5: Patterns Frequency in Cube Sensors API.

0 20 40 60 80 100 120 140 160 Early Directed URI Versionized API Metadata Retrievability Expressive Request Proactive Filtering ‘me’ Accessible Resources Versionized Resources Querified Authentication

Patterns Frequency in Droplit.io API

Figure 4.6: Patterns Frequency in Droplit.io API.

0 20 40 60 80 100 120 140 160 180 200 Early Directed URI Versionized API Metadata Retrievability Expressive Request Proactive Filtering ‘me’ Accessible Resources Versionized Resources Querified Authentication

Patterns Frequency in IBM Watson IoT API

(27)

0 5 10 15 20 25 30 Early Directed URI Versionized API Metadata Retrievability Expressive Request Proactive Filtering ‘me’ Accessible Resources Versionized Resources Querified Authentication

Patterns Frequency in Losant API

Figure 4.8: Patterns Frequency in Losant API.

0 20 40 60 80 100 120 140 Early Directed URI

Versionized API Metadata Retrievability Expressive Request Proactive Filtering ‘me’ Accessible Resources Versionized Resources Querified Authentication

Patterns Frequency in Microsoft Azure API

Figure 4.9: Patterns Frequency in Microsoft Azure API.

0 10 20 30 40 50 60 70 80 Early Directed URI Versionized API Metadata Retrievability Expressive Request Proactive Filtering ‘me’ Accessible Resources Versionized Resources Querified Authentication

Patterns Frequency in Particle API

(28)

0 5 10 15 20 25 30 35 40 45 50 Early Directed URI Versionized API Metadata Retrievability Expressive Request Proactive Filtering ‘me’ Accessible Resources Versionized Resources Querified Authentication

Patterns Frequency in SONOS API

Figure 4.11: Patterns Frequency in SONOS API.

0 1 2 3 4 5 6 7 8 9 Early Directed URI Versionized API Metadata Retrievability Expressive Request Proactive Filtering ‘me’ Accessible Resources Versionized Resources Querified Authentication

Patterns Frequency in The Things Network API

Figure 4.12: Patterns Frequency in The Things Network API.

0 5 10 15 20 25 Early Directed URI Versionized API Metadata Retrievability Expressive Request Proactive Filtering ‘me’ Accessible Resources Versionized Resources Querified Authentication

Patterns Frequency in thethings.iO API

(29)

0 2 4 6 8 10 12 14 16 18 20 Early Directed URI Versionized API Metadata Retrievability Expressive Request Proactive Filtering ‘me’ Accessible Resources Versionized Resources Querified Authentication

Patterns Frequency in Toon API

Figure 4.14: Patterns Frequency in Toon API.

5 Discussion

The different steps of the project went well as a whole, with only some minor difficulties. The documentation of the URIs for some of the APIs was poor, which caused less clarity and understanding. The main problem with the documentation was that the different parts of the URI were sometimes poorly explained or even not explained at all, causing us to guess the meaning of them. Even though we had these problems, we were able to divide the URI itself into different types of nodes, which was enough to understand the structure of it.

We have completed all the defined objectives and have been able to define eight design patterns in total for URIs of IoT REST APIs, which was the goal of this project. These design patterns were found and defined during the URI analysis, and the distribution between these eight design patterns was as follows: one for the Authority section, one for both Base and Query sections, five for the Main section and finally one for only the Query section. The fact that five out of eight design patterns were related to the Mainsection shows that the Main section is the most likely to have more variations out of the other sections.

(30)

6 Conclusion

Design patterns are widely accepted as reusable solutions to recurring design problems with benefits of reusability and easy to understand and maintain [1]. Design patterns can be useful in RESTful Web services and, in particular, for IoT APIs. The prospective IoT vendors can benefit from IoT APIs design patterns by designing and developing their APIs based on our suggested design patterns, which would increase the reusability and understandability of their APIs.

In this paper, we analyzed a set of 13 IoT APIs and proposed eight relevant design patterns based on the existing IoT APIs. Our key contributions are: (1) a thorough manual analysis of more than 1,300 URIs from 13 IoT REST APIs including IBM Watson and Microsoft Azure; (2) the definition of eight novel design patterns for URIs of IoT APIs that IoT vendors can use, and that would work as a common language for IoT APIs designers; and (3) a validation process that shows the defined design patterns are prevalent among the IoT APIs with 84% of URIs in our validation set being mapped to at least one design pattern.

6.1 Future Work

Future work for this project can be to reason if and why the derived design patterns are based on good design practices. This reasoning would be also useful to choose the best form out of all the forms that some patterns provide. Moreover, our list of design patterns can be extended by analyzing more APIs. Besides, developing a tool that can automati-cally detect design patterns in the URIs and recommend those for the API designers. The benefit of this tool is that a URI can be analyzed much faster, which will encourage API vendors to use these design patterns in their URIs.

(31)

References

[1] E. Gamma, Design Patterns: Elements of Reusable Object-oriented Software. Pear-son Education India, 1995.

[2] L. Richardson and M. Amundsen, RESTful Web APIs. O’Reilly, 2013. [Online]. Available: https://books.google.se/books?id=ppEVtAEACAAJ

[3] H. Subramanian and P. Raj, Hands-on RESTful Web API Design Patterns and Best Practices: Design, Develop, and Deploy Highly Adaptable, Scalable, and Secure RESTful Web APIs. Packt Publishing, 2019.

[4] S. Abbas and A. Ojo, “Applying Design Patterns in URI Strategies – Naming in Linked Geospatial Data Infrastructure,” in 2014 47th Hawaii International Confer-ence on System SciConfer-ences, 2014, pp. 2094–2103.

[5] I. Grønbæk, “Architecture for the Internet of Things (IoT): API and Interconnect,” in 2008 Second International Conference on Sensor Technologies and Applications (sensorcomm 2008). IEEE, 2008, pp. 802–807.

[6] W. Zhou, L. Li, M. Luo, and W. Chou, “REST API design patterns for SDN north-bound API,” in 2014 28th international conference on advanced information net-working and applications workshops. IEEE, 2014, pp. 358–365.

[7] L. Li, W. Chou, W. Zhou, and M. Luo, “Design patterns and extensibility of rest api for networking applications,” IEEE Transactions on Network and Service Manage-ment, vol. 13, no. 1, pp. 154–167, 2016.

[8] R. T. Fielding and R. N. Taylor, Architectural Styles and the Design of Network-based Software Architectures. University of California, Irvine Irvine, 2000, vol. 7. [9] M. D. Wilkinson, B. Vandervalk, and L. McCarthy, “The Semantic Automated Dis-covery and Integration (SADI) Web Service Design-pattern, API and Reference Im-plementation,” Journal of biomedical semantics, vol. 2, no. 1, p. 8, 2011.

[10] M. Masse, REST API Design Rulebook: Designing Consistent RESTful Web Service Interfaces. O’Reilly Media, Inc., 2011.

[11] A. McEwen and H. Cassimally, Designing the Internet of Things. John Wiley & Sons, 2013.

[12] A. Kazmi, Z. Jan, A. Zappa and M. Serrano. (2016) Overcoming the heterogeneity in the internet of things for smart cities. [Online]. Available: https://www.researchgate.net/publication/312232240_Overcoming_the_heterogen eity_in_the_Internet_of_Things_for_Smart_Cities

[13] N. W. Group. (2005) Uniform Resource Identifier (URI): Generic Syntax. [Online]. Available: https://tools.ietf.org/html/rfc3986