REST API Server with Delphi and XData 5: Read and Watch

TMS XData 5 has been released with lots of new features!

Photo by Glenn Carstens-Peters on Unsplash

Photo by Glenn Carstens-Peters on Unsplash

In addition to the recent release of TMS Aurelius 5, a new major version of TMS XData has been also released.

TMS XData 5 is the fifth major version of our framework to build multitier applications, including REST API server, and interface-based API client. It makes it easy to build server-side services that reach a broad range of clients, including browsers and mobile devices.

Among several features, TMS XData provides:

  • Automatic serialization/deserialization of pure Delphi objects, primitive types, method parameters;
  • Authentication and Authorization;
  • Powerful routing mechanism: route endpoints to methods in your code;
  • Automatic, zero-code Swagger/SwaggerUI support;
  • Interface-based client allows type-safe client applications without additional code;
  • Smooth TMS Aurelius integration allows CRUD endpoints of database entities automatically.

The new features released with XData 5 were also antecipated in a previous blog post,

The what’s new section in the documentation provides you with a full list, but here we will list a few:

Attribute-based Authorization

Developers will be able to just add authorization attributes to methods (service operations) or entities (automatic CRUD endpoints) and everything will be applied accordingly. Fine-tuning the protection of your REST API will never be as simple.

  [Authorize]
  IDocumentService = interface(IInvokable)
    procedure Insert(Value: TDoc);

    [AuthorizeScopes('user, editor')]
    procedure Modify(Value: TDoc);

    [AuthorizeScopes('admin')]
    procedure Delete(DocId: string);

    [AuthorizeClaims('email')]
    procedure Approve(DocId: string);
  end;

In the example above, all methods (endpoints) require authentication, because the interface has an Authorize attribute that propagates to all methods. So, to invoke Insert, user must be authenticated. Still, to invoke Modify, the user must be authenticated and have either user or editor scope in its credentials. He must be admin to invoke Delete, and finally to approve a document, user must have an email in its claims.

It’s also worth noting that the same strategy applies to entities that generate automatic CRUD endpoints:

  [Entity, Automapping]
  [EntityAuthorize]
  [EntityAuthorizeScopes('editor', [TEntitySetPermission.Modify, TEntitySetPermission.Insert])]
  [EntityAuthorizeScopes('admin', [TEntitySetPermission.Delete])]
  TCustomer = class
  {...}
  public
    property Id: Integer read FId write FId;
    property Name: string read FName write FName;
  end;

To access customer endpoints, user must be authenticated. But he must have editor privileges to modify and insert (PUT and POST) and must be admin to invoke DELETE. Easy and straightforward.

Async/Await Support in Web Applications

TMS XData is smoothly integrated with TMS Web Core, the TMS framework to build web applications.

Now your can use async/await mechanism in TXDataWebClient methods that invoke XData server endpoints. As an example, invoking a XData REST API endpoint asynchronously will be as easy as doing this:

PendingOrders := await(XClient.List('$filter=Status eq pending'));
if PendingOrders.Count = 0 then
  Exit; // no pending orders to process

The single line above will build the HTTP request with proper URL endpoint and HTTP method, invoke it, deserialize the returned JSON into a list of TOrder objects, and all asynchronously! The await function will guarantee that the next line will be executed only after the async execution is executed. Can’t get easier than that.

Multitenant Servers

This is a feature released with TMS Aurelius, which now has the global filter mechanism, allowing you to build multitenant applications.

But XData now includes a few nice mechanisms to integrate with such Aurelius filters that makes building multitenant servers very easily!

From a single handler for the event OnManagerCreate, you can enable the “Multitenant” filter for all requests:

  Manager.EnableFilter('Multitenant')
    .SetParam('tenantId', 'acme');

After you’ve enabled the “Multitenant” filter passing the proper id, you can use the Aurelius object manager as usual. But any request you do, like in the example, asking a list of products, will add the tenant filter.

Requests will not only apply global filters for queries, but also will enforce the filter in INSERT, UPDATE and DELETE operations.

Also building multi-database multitenant server will also be easy with the new TMultiTenantConnectionPool:

  FMultiPool := TMultiTenantConnectionPool.Create(
    TXDataHttpHeaderTenantResolver.Create('tenant-id'),
    TDBConnectionPoolFactory.Create
    );

The pool will automatically choose the correct database based on the HTTP header tenant-id – or any other criteria you might choose. All transparently.

Come See it Live!

Want to know more about XData? Want to see the new features live?

The free webinar “Introducing XData 5” will be held next Wednesday, March 31st, at 4pm UTC at the TMS Web Academy.

In this webinar, Wagner Landgraf, TMS XData architect, will explain to newcomers what TMS XData is about, how to use it, and then show all the new features in action, with real code.

And of course, it will be a live session: you can ask questions and participate! Register now for the “Introducing XData 5” webinar and learn more about this amazing REST API framework!

Wagner R. Landgraf