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

Adding Tools into the IDE

Adding tools into the RAD Studio IDE.

Now, this isn’t new! But, this week in Sweden, I spoke to a developer who has been using Delphi for years and didn’t know about this handy trick. As I am currently working over a series when I’m developing a RESTful backend and client, it makes sense to show how to add the REST Debugger into the IDE menus.

“Configure Tools” inside RAD Studio

At the top of the IDE you will find the Tools Menu. You might normally go straight to the Options (to configure the IDE) or Getit Package Manager (to download components), but there is also Configure Tools… which manages the list of items underneath it.

Continue reading Adding Tools into the IDE

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

InterBase Temporary Tables

InterBase Temporary Tables

This last week, InterBase 2020 has been released bringing the awesome Tablespaces feature into play. This new feature enables splitting the database into groups of tables (a Tablespace) that can then be put onto different physical disks (to aid performance) but also enables partial backup of a database. I plan to cover this new feature, and some useful ideas about how to use them in an article in the coming weeks, but first, I want to address something a bit older in InterBase that I’ve not blogged about before. Why? Well recently, I was at a UK roadshow event, when content about InterBase 2020 was being previewed, and a developer said “This new stuff is cool, but what I really need is the ability to put data into a table temporarily in InterBase, and have it isolated from other transactions…. Other databases have it, when will InterBase get it?” Well, InterBase has had this for years!

Continue reading InterBase Temporary Tables

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.

Programming with Delphi & InterBase