NG ConnectionPack Guide


Overview


LMD NG ConnectionPack is a part of Next Generation (NG) package suite. All these packages are based on new IDE and language features of latest Delphi IDE versions. NG ConnectionPack provides the ability to access to Web based services (REST services), such as cloud storage services.

 

The first thing required to connect REST services is to register your application. This is usually done by creating an account in the developer's zone of the corresponding service provider web site, and then filling the application description data, such as the Name, Logo, and some other parameters. As a result you'll get application's ClientID and Secret codes. Provided ClientID and Secret values should be copied into corresponding properties of the NG ConnectionPack components. More precisely the registration process is described in Application Registration section.

 

After you've got your ClientID and Secret codes NG ConnectionPack components will be able to connect to the corresponding REST services. However, application's end-users are also required to authenticate themselves in the corresponding services. This process is called authentication, and performed using modal dialog, where the corresponding REST service login page is shown to the user along with your registered application name, logo and required access rights. After successful user login, the service provides so called access_token (and some other info), which is used subsequently to sign Http requests.

 

Its important to note that returned authentication info can be stored and loaded using SaveState and LoadState methods, and its strongly recommended to use there methods to persist authentication info between your application runs. First, this will prevent the user from logging in each time your application run. Second, for some services there is an explicit limit of tokens, which can be returned, and thus the requirement of storing authentication info between application runs are stated explicitly in the service's documentation. Current access token can be reset using ResetToken method; the user will be forced to re-authenticate after token reset.

 

NG ConnectionPack shows authentication dialog as required on demand; there no way to show login dialog explicitly, but you can always check that the authentication info is Ok, using RefreshAccess public method. Look at Authentication section for further description.

 

After successful user authentication, real features of the services become available to the application. Here its important to note that NG ConnectionPack components implements state-less wrappers for corresponding REST services. Components do not store internally any returned data, such as file objects or calendar events. On each request new set of objects will be returned. Most of such objects are really implemented as Delphi records (thanks to Delphi new language features, which allow the records to have properties and methods); so, the memory management is mostly automatic. Look at State-less and Memory Management section for more info.

 

NG ConnectionPack ships with visual tool, called API Explorer, which accessible at design-time via Delphi's Tools menu sub-item or as a component editor for NG ConnectionPack components. API Explorer provides an easy and intuitive way for REST operations execution, including uploading and downloading data without code writing. Its a great tool for test purposes and services understanding. Please read here.

 

Note: Starting from 2018 release NG ConnectionPack has been almost fully re-designed. The packages no longer provide unified interface for cloud storage components. Instead we've concentrated on the formal way of implementing REST services, which allow to provide most complete functionality for each service, with API structure, closely related to corresponding services API and documentation. For more information about package architecture please look here.

 

Components

 

NG ConnectionPack include many service components, accessible from the Delphi's component palette at design-time. The list of supported services is big, and following only some examples are represented:

 

TNGDropbox

TNGBoxNet

TNGGCalendars, TNGGDrive, TNGGMail, TNGGPeople, TNGGSheets, TNGGTasks, ect.

Full service list along with descriptions and documentation links is provided in Service List topic.

 

Each component is a descendant of TNGRestService base class, which offers application settings management, authentication/token management and access scopes management.

 

Otherwise, each component have its own public interface, which is closely related to the corresponding REST service API. Its a good idea to read corresponding REST services API documentation to understand its methods and related data structure; we cannot provide the documentation for each service, because of big amount of services and its methods/data.

 

Features

 

Following is a short feature list of NG ConnectionPack package:

 

Provides most complete state-less support of various REST service APIs.

Provides OAuth 2.0 authentication dialog, along with a custom auth-UI interface for building application specific authentication dialogs.

Provides API Key authentication method for Google services.

Allows to store/load/reset authentication state to prevent explicit user authentication each time application starts.

Provides a smart memory management model, simplifying the package usage.

Provides grouping capability, which allow to implement a single authentication into a group of services of the same vendor (specifically - for Google services).