Top 5 Tips for RESTful APIs and Closing the Loop on OAuth2.0

Click the button below to download a free copy of RAD Studio with C++Builder to try out the code samples and resources referenced in this article.

Introduction

Many of the devices and gadgets that comprise the Internet of Things require that end users sync data to cloud services via a 1st party app. End user data is then exposed to developers over a RESTful API from the hardware vendor cloud services. It is up to each vendor to implement the OAuth2 protocol and define their own RESTful API for their service and as such there is no single solution for how to connect, authorize, and eventually consume end user data.

This top five list is to help equip you with the tools and knowledge needed to analyze how a vendor implements OAuth2.0, how to interface with RESTful APIs, and ultimately gain access to end user data.

#5 - Definitions of OAuth2.0 Authorization Framework

The OAuth2.0 Authorization Framework spec is defined by the IETF in RFC 6749. The goal of OAuth2.0 is to decouple resource owner (end user) credentials from their resources (end user data). A separate set of credentials are supplied by the resource server (vendor cloud services) to the client (3rd party application) which grants access to resources. This effectively enables 3rd party apps to access end user data without having to store their user name and password.

All OAuth transactions occur over HTTP.

Within the context of IoT vendors, OAuth2.0 defines four roles as such:

resource owner

This represents the end-user that uses a 1st party app to sync IoT data to a vendors cloud service. The vendor cloud service must then provide a mechanism for the resource owner to grant access to a protected resource. This is typically done through the vendors web portal login gateway.

resource server

A vendor cloud service that is capable of identifying and processing valid access_tokens in exchange for access to a protected resource. A protected resource will typically be end user data that represents sensor or other data collected by IoT gadgets and devices.

client

This is the application a 3rd party developer will create that will ultimately consume end-user data (protected resource) on behalf of the end user (resource owner). This application can live as a desktop app, mobile app, middleware, other enterprise services, or even on a Thing itself.

authorization server

The vendor cloud service that is capable of issuing access tokens to the client after successfully authenticating the resource owner and obtaining authorization.

An access token is defined by the RFC 6749 standard as:

"a string denoting a specific scope, lifetime, and other access attributes. Access tokens are issued to third-party clients by an authorization server with the approval of the resource owner. The client uses the access token to access the protected resources hosted by the resource server."

#4 Protocol Flow - Obtaining Access Token

One way for the resource owner (end-user) to provide authorization to the app is to use the Web Browser Component which allows input of username and password to the resource server (vendor cloud service). For a working example of this process, see my blog post on consuming the MISFIT REST API.

In order to access a protected resource, the client must include an access token as part of the RESTful API call. The following steps are a generic outline for obtaining a valid access token as defined by the RFC 6749 standard.

1. The client requests authorization from the resource owner. The authorization request can be made directly to the resource owner or preferably indirectly via the authorization server as an intermediary.
2. The client receives an authorization grant, which is a credential representing the resource owner's authorization, expressed using one of four grant types defined in this specification or using an extension grant type. The authorization grant type depends on the method used by the client to request authorization and the types supported by the authorization server.
3. The client requests an access token by authenticating with the authorization server and presenting the authorization grant.
4. The authorization server authenticates the client and validates the authorization grant, and if valid, issues an access token.
5. The client requests the protected resource from the resource server and authenticates by presenting the access token.
6. The resource server validates the access token, and if valid, serves the request.

#3 Locally Store Access Token

Once a valid access token is obtained, it is a good idea to save that access token to the protected internal storage of the client device. Working with INI files to store access tokens has the advantage of streamlining the reading and writing of data using the TIniFile class. Using an INI file helps avoid having to acquire a new access token every time the client application runs.

Before using a stored access token to make a RESTful API calls to obtain a protected resource, first make a test call to ensure that the token is still valid. If it is not valid, the client application should re-initiate the access token request process and then update the validated access token in the INI file.

Loading and Deploying Files is streamlined via the System.IOUtils unit which makes creating, updating, and deleting INI files very straight forward for both Object Pascal and C++.

Take care to not store the INI file in a publicly addressable or shared file space on the client device. On Android, for example, the INI file should be placed in assets\internal.

In C++, a handle to the file can be obtained.

IniFilePath = System::Ioutils::TPath::Combine(
System::Ioutils::TPath::GetDocumentsPath(), "vendor_service.ini");

Ini = new TIniFile(IniFilePath);

Once a handle to the INI file is obtained the contents can be queried.

AccessToken = Ini->ReadString( "VendorServiceName", "accessToken", "" );

Once a valid access token is obtained you are ready to make calls to a RESTful API service.

#2 Use the REST Debugger and REST Components for RESTful API Calls

The REST Debugger is built on top of the Embarcadero REST Library, which is a framework for accessing REST-based web services (REST stands for Representational State Transfer). The REST Debugger allows developers to make ad hoc RESTful API calls and easily spelunk through any returned JSON blobs. The REST Debugger is capable of generating REST components which can be directly copy and pasted into the Appmethod IDE. This is a very convenient, fast, and powerful approach to prototype and build REST integration and tie in functionality with your application.

Here is a great collection of DocWiki entries pertaining to the REST Debugger and Rest Components

http://docwiki.embarcadero.com/RADStudio/XE7/en/REST_Client_Library

http://docwiki.embarcadero.com/RADStudio/XE7/en/REST_Debugger

http://docwiki.embarcadero.com/CodeExamples/XE7/en/RESTDemo_Sample

http://docwiki.embarcadero.com/RADStudio/XE7/en/Tutorial:_Using_the_REST_Client_Library_to_Access_REST-based_Web_Services

There are also a number of blog entries and videos that dive into the details of using both the REST Debugger and the REST Client Library

Riding the waves with REST and C++Builder for iOS

Using the REST Debugger and REST Components to Query Twitter

Using the REST Debugger and REST Components to Control Phillips Hue Lux Light

Integrate Cloud Services with the REST/JSON Client

#1 Use a Middleware Solution to Aggregate Data

Vast amounts of data are being generated by IoT gadgets and devices which creates opportunities for new and meaningful kinds of analytics. IoT data analytics creates a new revenue stream for the vendor. Even though end user data (protected resources) is made open and available over RESTful API calls, the access can be limited.

When it comes to consuming a protected resource, not all vendors will expose end user data in the same way. Some will have rate limits to the number of RESTful API calls and others will restrict the date range allowing queries to only go back, for example, 30 days.

This can cause problems to client applications that need to have robust access to end user data. Limitations placed by the vendor on RESTful API calls can completely break the deep functionality desired by a client application. To help solve this problem, and to truly own end user data, a middle ware solution can be introduced to create an aggregated data source.

The Enterprise Mobility Services (EMS) is a new turnkey solution for today’s interconnected, distributed apps, offering an easy to deploy middleware server that hosts loadable custom API and data access modules. It’s based on open and standard technologies, including REST HTTP calls and JSON data formats, and provides major SQL database drivers along with an encrypted embedded and server SQL database. With its user management and authentication with user and API analytics, Enterprise Mobility Services is ideal for enabling secure access from mobile apps to Enterprise Databases. EMS is a middleware solution that is stateless, restful, scalable, and secure.

As new data is generated by a given IoT device, the EMS Server can consume the vendor RESTful API and on regular intervals to obtain a copy the newly generated protected resources. Relying on your own RESTful API layer will ensure that your client application will have unfettered access to all of the protected resources within the system.

For more information on the EMS Server, please check out these resources:

EMS Client Application

Tutorial: Implementing Your First EMS Client Application

Learn more.