Category Archives: General

For stuff I forget to categorise! Doh!

Attributes for Documenting TEMSDataSetResource

Attributes for Documenting TEMSDataSetResource

I recently blogged about a number of RAD Server topics, including using TEMSDataSetResource, (the component that enables a TDataSet to be expose as a RESTful resource, and manage all the List, Get, Put, Post, Delete methods – very cool!), how to set named parameters for the TEMSDataSetResource documentation (where multiple keys are passed in e.g. with Master Detail relationships (reviewed below)), and how the YAML and JSON documentation is auto generated with custom RESTful resources / end points

Typically, each custom REST endpoint method (List, Get, Put, Post, Delete), would be supported by separate procedures in the code, with each having their attributes to support documentation, resource name etc.

Typically, List and Post would have no parameters, but Get, Put and Delete would all take the ID of the object being requested / updated / removed. The approach with separate procedures in code makes it very easy to add attributes to list parameters based on their method. Which leads me to the challenge with TEMSDataSetResource. How do you define parameters for the different methods with the same component?

ResourceSuffix Attribute

In the last blog, I highlighted how the ResourceSuffix can be used to set the name of values in the resource, rather than using the default ‘id’ value. – This is essential when multiple parameters are used.

[ResourceName('exams')]
  TExamsResource1 = class(TDataModule)
  [ResourceSuffix('./{EXAM_ID}/questions')]
  [ResourceSuffix('List', './')]
  [ResourceSuffix('Get', './{QUESTION_ID}')]
  [ResourceSuffix('Post', './')]
  [ResourceSuffix('Put', './{QUESTION_ID}')]
  [ResourceSuffix('Delete', './{QUESTION_ID}')]
  dsrEXAM_QUESTIONS: TEMSDataSetResource;

The documentation picks up the parameter name automatically into the YAML documentation for that method. But now it needs to be defined. In this example, EXAM_ID is required for each call, and QUESTION_ID is also required, but only for the Get, Put and Delete.

EndPointRequestParameter Attribute

To define the required attribute EXAM_ID, it is possible to use a single EndPointRequestParameterAttribute (note: Attribute part of the name at the end is optional)

[EndPointRequestParameter(
   TAPIDocParameter.TParameterIn.Path, 
   'EXAM_ID', // Param name
   'EXAM_ID for the selected /exam/ ', //about it 
   true, // required
   TAPIDoc.TPrimitiveType.spInteger, // type
   TAPIDoc.TPrimitiveFormat.Int64, // ext format
   TAPIDoc.TPrimitiveType.spInteger, // array?
   '', // Scheme
   '')] // Reference
dsrEXAM_QUESTIONS: TEMSDataSetResource;

But here in lies the twist….. If we did the same for QUESTION_ID, we would have issues with it showing for List  and Post. The answer (once found) is actually quite simple. You need to define the parameters in the same way as the ResourceSuffix. e.g.

[EndPointRequestParameter(
   'Get',
   TAPIDocParameter.TParameterIn.Path, 
   'QUESTION_ID', // Param name
   'QUESTION_ID for the question to get', //desc
   true, // required
   TAPIDoc.TPrimitiveType.spInteger, // type
   TAPIDoc.TPrimitiveFormat.Int64, // ext format
   TAPIDoc.TPrimitiveType.spInteger, // array?
   '', // Scheme
   '')] // Reference
[EndPointRequestParameter(
   'Put',
   TAPIDocParameter.TParameterIn.Path, 
   'QUESTION_ID', // Param name
   'QUESTION_ID for question to update', //desc
   true, // required
   TAPIDoc.TPrimitiveType.spInteger, // type
   TAPIDoc.TPrimitiveFormat.Int64, // ext format
   TAPIDoc.TPrimitiveType.spInteger, // array?
   '', // Scheme
   '')] // Reference
[EndPointRequestParameter(
   'Delete',
   TAPIDocParameter.TParameterIn.Path, 
   'QUESTION_ID', // Param name
   'QUESTION_ID for the question to delete ', 
   true, // required
   TAPIDoc.TPrimitiveType.spInteger, // type
   TAPIDoc.TPrimitiveFormat.Int64, // ext format
   TAPIDoc.TPrimitiveType.spInteger, // array?
   '', // Scheme
   '')] // Reference
dsrEXAM_QUESTIONS: TEMSDataSetResource;

The issue here however, is that as soon as you define method specific attributes, you stop inheriting the defined parameters for the TEMSDataSetResource. This means you need to define all of parameters them for that method. (so you need to add in the EXAM_ID again for each of the Get, Put and Delete methods with extra EndPointRequestParameter’s) e.g..

[EndPointRequestParameter(
   'Get',
   TAPIDocParameter.TParameterIn.Path, 
   'EXAM_ID', // Param name
   'EXAM_ID for the exam to get', //desc
   true, // required
   TAPIDoc.TPrimitiveType.spInteger, // type
   TAPIDoc.TPrimitiveFormat.Int64, // ext format
   TAPIDoc.TPrimitiveType.spInteger, // array?
   '', // Scheme
   '')] // Reference
[EndPointRequestParameter(
   'Get',
   TAPIDocParameter.TParameterIn.Path, 
   'QUESTION_ID', // Param name
   'QUESTION_ID for question to update', //desc
   true, // required
   TAPIDoc.TPrimitiveType.spInteger, // type
   TAPIDoc.TPrimitiveFormat.Int64, // ext format
   TAPIDoc.TPrimitiveType.spInteger, // array?
   '', // Scheme
   '')] // Reference
...

EndPointRequestSummary Attribute

The same approach can also be used for the EndPointRequestSummaryAttribute.

 [EndPointRequestSummary
  ('Exams', // Tags
   'Exams', // Summary
   'Each Exam has a list of questions, each containing multiple answers', // Description
   'application/json', // Produces
   '')] // Consumes

or 

 [EndPointRequestSummary
  ('Get',  // Method
  'Exams', // Tags
  'Exams', // Summary
  'Fetches an specific Exam', // Description
  'application/json', // Produces
  '')] // Consumes

etc

More about attributes…

See Custom_API_Documentation on DocWiki

Developing client applications using RESTful master-detail data with TRESTResponseDataSetAdapter

This is part 3 in my series of developing an REST server and client application and will focus around using the TRESTResponseDataSetAdapter.

In my last two posts, we have created a REST server with a fully documented API using YAML , and exposed 3 datasets with master detail relationships over REST using zero lines of code.  If you have not read and watch the videos. I would suggest starting there. – It’s now time to consume the API into a cross platform Delphi Client.

Steps to making the client

The video and supporting blog post take you through the following.

  1. Setting up components to connect to the REST API. (RAD Style)
  2. Converting the JSON into a master detail datasets (based on the current item in the JSON data)
  3. Enabling the data in the UI with LiveBindings and zero code.
  4. Tricks for reducing API calls.

Continue reading Developing client applications using RESTful master-detail data with TRESTResponseDataSetAdapter

Master Detail data in RAD Server using TEMSDataSetResource

Master Detail data in RAD Server

The TEMSDataSetResource is a very powerful component that enables rapid development of full document REST API’s for TDataSet using RAD Server. Using TEMSDataSetResource, along with traditional master detail relationship configurations, it is possible to expose, and automatically document data APIs via REST with no code at all.

In this article, I will cover sharing master detail data with no code, but also how to roll your own REST endpoint to cover more advanced detail with detail embedded calls.

In my previous article, I updated advise on getting started with Swagger UI, using the new WebFiles feature of RAD Server (from 10.3.2) as a way to view your documentation as you build your backend services API. This article will build upon the sample application created in that post.

Continue reading Master Detail data in RAD Server using TEMSDataSetResource

Embedding Swagger UI into RAD Server

This post is an update to the original post written previously showing Swagger UI being used with RAD Server, covering new features of RAD Server.

Why Embed Swagger UI into RAD Server?

Swagger UI (as previously discussed) is a great option for checking your documentation and working with the REST API. One of the challenges has always been CORS (Cross Origin Resource Sharing) that makes execution of the code a challenge when developing.

There are a few options now however. You can either work around this with browser plug-ins, (as seen before), enable CORS in the emsserver.ini under [Server.APICrossDomain], or embed swagger-ui inside your RAD Server instance.

In this video, I cover the latter option. You can watch how to get documentation up and running. The video shows how to configure your EMSServer.ini to share the external resource through RAD Server and also modify the downloaded files to automatically load up the API documentation directly from RAD Server.

WebFiles in RAD Server EMSServer.ini

The key to making this work is the WebFiles option that was added to RAD Studio in 10.3.2. This was primarily added to make it easier to serve out web content and support ExtJS for doing web client development under the Architect edition of RAD Studio, however, this also has the benefit of making other content available to share.

Continue reading Embedding Swagger UI into RAD Server

Opening a PDF on Android with Delphi

Intents on Android using API 26 to open PDF documents.

Recently, the Google Play store updated its requirements so the target API level of 26 was used to get new apps submitted. While this was reasonably easy to achieve through updating the AndroidManifest.Template, the change to the newer API changed the behaviour of my application.

Before the update, I would download a file to the CachePath and then share to a public folder. I would then get a URI for the public folder path file and share via Intents.  Following the update, this no longer worked. After a little research, I discovered this was due to the changes in the Android security system, that actually, make a lot of sense. Rather than sharing the file outside the application, you now provide tempory access to it via the Intent. To achieve this, you need to setup a Provider, (this is done via XML) and then programmatically provide the path as a ‘content://’ URI, set flags for allowing read / write access via the intent and share it.

The video shows how to achieve this and demo’s the working code. To help, below are some of the XML blocks you will need upon the way.

Adding Provider

Add this to the AndroidManifest.template in the source code root folder, before the </application> tag. This is then used to build all Android apps.

<provider android:name="android.support.v4.content.FileProvider"
android:authorities="%package%.provider"
android:exported="false"
android:grantUriPermissions="true">
<meta-data
android:name="android.support.FILE_PROVIDER_PATHS"
android:resource="@xml/fileprovider" />
</provider>

Provider file

Create a fileprovider.xml (or whatever file name you set in android:resource when declaring the provider).

<?xml version="1.0" encoding="utf-8"?>
<paths xmlns:android="http://schemas.android.com/apk/res/android">
<cache-path name="bbresources" path="bbresources/"/>
</paths>

More flags and details for Provider Files can be found on the Android documentation

RAD Server and Enterprise Connectors

Connected Systems

Many years ago I was the lead developer for a software development company that was a market leader in the leisure industry. Back in the day, we were using Delphi 3 and then Delphi 5 to create the software. The software was a complete CRM that interfaced with access control systems, card readers, ran in multiple languages, and offered everything from reservation management to debt collection.

So why am I starting my post with this trip into the past? – In short, One thing that was true then is even truer today. The more customers the software won, the more systems we were asked to integrate with: From a finance point alone, customers wanted to consolidate their business accounts into Sage, QuickBooks and the like because they were the best at doing specific accounting jobs. While the software my team wrote managed a large percentage of the daily business, it was part of the mix that made up a customers technological capability/software systems. – No App is an Island!

Working with so many different systems and API’s can be a real handful, different API’s work in different ways which adds testing complexity,  and more skills and knowledge that needs to be learned. If it was working with text files, SOAP (needed to get to Delphi 6 (ok 7)  for that), sockets, or a growing number nowadays via JSON and HTTP, a lot was required to manage and maintain these connections (and develop the new ones each time they were needed).

Being at the heart of the connection!

While connecting to other systems was important, one thing that really establishes a product is what connects to it! One of the biggest boost sales ever received (while I don’t think they really appreciated it at the time) was the development of an external use API into the core system. This for the first time enabled customers to build their own extensions that worked with our software. Rather than limiting the potential for custom development, this added the desire for the customer to build their own applications that became reliant on our systems. Those that built on our frameworks became worth a lot more in the long term value that those that didn’t. But why is that important today?

RAD Server and Enterprise Connectors

This week has seen the launch of a brand new initiative from Embarcadero, who have partnered with CData to provide Enterprise connectivity to 80+ Enterprise applications.

So? I can program an API right…

Well, using FireDAC, these connections are easily added to any application as a database driver (just like connecting to InterBase or Oracle or any other SQL database).  It then manages the magic of converting all API’s into standards base SQL to work with!

That means,

  • live data at design time,
  • easy configuration of connections (just like any other database)
  • no need to learn multiple API’s…
  • a far simpler development process!

This also means easy access to FireDAC’s core capabilities such as LocalSQL etc.

Enterprise connectors coupled with RAD Server enable developers using RAD Studio, Delphi or C++Builder to build amazing connected middle-tier systems rapidly, that are shared using modern JSON connectivity. With the ability to easily connect to so many different data sources, and make those available via JSON and YAML documentation, you can deliver a single sign-on server with amazing connectivity very rapidly. With API usage analysis built into RAD Server, management of the heart of your customer’s software systems is easy to achieve, making your products an integral part of their future.

Get RAD Server for FREE!

Right now (Until 30th June 2017), a Site license of RAD Server is available free with Architect editions of RAD Studio, Delphi and C++Builder.  To learn more about RAD Server, I suggest checking out RAD Server home page or searching RAD Server on YouTube.

Enterprise Connectors – Beta

The Enterprise connectors beta is now available to those on the latest version of RAD Studio, Delphi or C++Builder. Visit the link here to find out more about the 80+ Enterprise systems included, such as Salesforce.com, SugarCRM, Google Analytics, MailChimp, Microsoft SharePoint, Paypal and Oracle Eloqua spanning Accounting, CRM, Marketing, NoSQL, eCommerce, Social Networking and more.

Video: Adding InterBase 2017 ToGo to RAD Studio 10.2

InterBase 2017 is now available for installation directly into RAD Studio via GetIt for use in Delphi and C++Builder applications across Windows, macOS, iOS, Android and also for Linux.

While a Linux InterBase Server Edition has been available for many years with InterBase, the introduction of the new Delphi Linux compiler in 10.2 Tokyo has ensured the addition of Linux as a new platform supported by ToGo.

Adding InterBase ToGo to the RAD Studio IDE

To install ToGo, just open GetIt in the RAD Studio IDE, (Tools > GetIt Package Manager) and search for InterBase.

 

From there you can install both the InterBase 2017 Developer Edition server and also the InterBase ToGo libraries.

InterBase Server enables multiple connections to the same database either locally or over a network. InterBase ToGo is a dynamically loaded version of the InterBase engine that runs in process for local connections and data storage or to act as a client driver for a remote conenction.

License and Video

Watch the video and see how to add InterBase ToGo into your Delphi and C++Builder applications.

Click the link here for a free trial license of InterBase ToGo.

If you are new to Database Development, then check out Cary Jensen’s latest FireDAC book that uses InterBase in a lot of the examples.

FireDAC Book – Using InterBase

New book – Delphi in Depth: FireDAC

There has been a growing stream of Delphi books in the last year covering everything from cross-platform development with FireMonkey to coding best practices around OOP. The latest book to be released is by long time Delphi Author Cary Jensen, specifically looking at database development with the cross-platform enabled FireDAC.

If you have been developing with Delphi for any amount of time, then you will probably know about Cary Jensen.  For those who don’t, Cary has written more than twenty-five books on software development, including some of the most popular works on ClientDataSets. Cary is an Embarcadero MVP and has been providing training, consultancy, and software development services since 1998.

Cary’s latest book, Delphi in Depth: FireDAC is now out and available covering 17 chapters about using FireDAC, the blazingly fast multi-platform database components from Embarcadero.

In Cary’s own words from his blog – this is the NEW goto book for database development with Delphi – and from a quick scan – I completely agree!

 I felt that this book should be more than just a FireDAC book. It should be a book that deserves to be on the shelf of every Delphi database developer. For the new Delphi database developer who is unfamiliar with the “Delphi way” of doing things, this book contains discussions of and demonstrations of the essential techniques that every Delphi database developer needs to know. This includes concepts like the TDataSet interface, the current record, and how to read to and write from TFields. (Just a note here, this book assumes you are using Delphi XE6 or later.)

Spanning over 500 pages, the book is full of examples, tips and techniques for making your database applications scream!

The book starts with an overview of the Features of FireDAC, 8 pages of high-level notes about the breadth of FireDAC – everything from Cross platform support, to ArrayDML, to DataType mapping and using LocalSQL (a very cool feature of FireDAC).

The book then helps you get started in the IDE and your applications before moving into the more advanced topics.

The other topics… see Cary’s blog. It’s well detailed. There are  17 if them, but in summary:
Chapter 1: Overview of FireDAC
Chapter 2: Connecting to Data
Chapter 3: Configuring FireDAC
Chapter 4: Basic Data Access
Chapter 5: More Data Access
Chapter 6: Navigating and Editing Data
Chapter 7: Creating Indexes
Chapter 8: Searching Data
Chapter 9: Filtering Data
Chapter 10: Creating and Using Virtual Fields
Chapter 11: Persisting Data
Chapter 12: Understanding FDMemTables
Chapter 13: More FDMemTables: Cloned Cursors and Nested DataSets
Chapter 14: The SQL Command Preprocessor
Chapter 15: Array DML
Chapter 16: Using Cached Updates
Chapter 17: Understanding Local SQL

InterBase inside

The book uses the IoT Award winning InterBase for the examples. InterBase is the cross-platform SQL database for Windows, macOS, iOS, Android and Linux.

To download the latest developer edition of InterBase for free click here.