Overview

TMS XData is a Delphi framework that allows you to create HTTP/HTTPS servers that expose data through REST/JSON. It is highly integrated into TMS Aurelius in a way that creating XData services based on applications with existing Aurelius mappings are just a matter of a few lines of code. XData defines URL conventions for adressing resources, and it specifies the JSON format of message payloads. It is heavily based on the OData standard. Such conventions, with the benefit of existing Aurelius mapping, allow building a full REST/JSON server with minimum writing of code. TMS XData uses TMS Sparkle as its core communication library.

TMS XData product page: https://www.tmssoftware.com/site/xdata.asp

TMS Software site: https://www.tmssoftware.com

TMS XData is a full-featured Delphi framework that allows you to create REST/JSON servers, using server-side actions named service operations, and optionally exposing TMS Aurelius entities through REST endpoints. Consider that you have an Aurelius class mapped as follows:

[Entity, Automapping]
TCustomer = class
strict private
  FId: integer;
  FName: string;
  FTitle: string;
  FBirthday: TDateTime;
  FCountry: TCountry;
public
  property Id: Integer read FId write FId;
  property Name: string read FName write FName;
  property Title: string read FTitle write FTitle;
  property Birthday: TDateTime read FDateTime write FDateTime;
  property Country: TCountry read FCountry write FCountry;
end;

With a few lines of code you can create an XData server to expose these objects. You can retrieve an existing TCustomer with an id equal to 3 using the following HTTP request, for example:

GET /tms/xdata/Customer(3) HTTP/1.1
Host: server:2001

And the JSON representation of the customer will be returned in the body of the HTTP response:

{
  "$id": 1,
  "@xdata.type": "XData.Default.Customer",
  "Id": 3,
  "Name": "Maria Anders",
  "Title": "Sales Representative",
  "Birthday": "1980-05-20",
  "Country": null
}

You can perform changes to objects through the REST interface, using a POST method to create new objects, DELETE to remove objects, and PUT or PATCH to update the objects. The following example will change the value of the FTitle property of the customer resource specified in the previous example:

PATCH /tms/xdata/Customer(1) HTTP/1.1
Host: server:2001

{ 
  "Title": "Marketing Manager" 
}

You can also perform queries on existing objects. The following example will retrieve all customers with a country name equal to "USA", ordered by the customer's name.

GET /tms/xdata/Customer?$filter=Country/Name eq 'USA'&$orderby=Name&$top=10 HTTP/1.1
Host: server:2001

The server will return a JSON array of objects containing all the filtered objects. You can use query paging to restrict the number of objects returned in each request.

Also, you can use service operations to implement custom business logic that uses Aurelius objects. By defining an interface and an implementation...

type
  [ServiceContract]
  IMyService = interface(IInvokable)
  ['{F0BADD7E-D4AE-4521-8869-8E1860B0A4A0}']
    function GetTopCustomersByState(const State: string): TList<TCustomer>;
  end;

{...}
function TMyService.GetTopCustomersByState(const State: string): TList<TCustome>;
begin
  Result := TXDataOperationContext.Current.GetManager.Find<TTCustomer>
    .Where(TLinq.Eq('State', State) and TLinq.Eq('Category', TStatus.VIP))
    .List;
end;

...you can easily invoke them from a Delphi client...

Client := TXDataClient.Create;
Client.Uri := 'http://server:2001/tms/xdata';
MyService := Client.Service<IMyService>;
TopNYCustomers := MyService.GetTopCustomersByState('NY');
// process customers

...or from an HTTP client:

POST /tms/xdata/MyService/GetTopCustomersByState HTTP/1.1
Host: server:2001

{
  "State": "NY"
}

Please refer to the Introduction topic of this manual which lists all major topics to learn more about XData and its features.

Features

Here is a list of main features of the TMS XData framework:

Server based on the REST/JSON architecture.
Easily accessible from different client platforms. For example: .NET, Java, JavaScript (since it is based on REST/JSON).
Uses standard POST, GET, PUT and DELETE HTTP methods for data request and data modification operations.
Service Operations for custom server-side business logic.
Partial update of objects (PATCH).
Full-featured query mechanism.
Well-defined JSON representation of resources including entities, associations, streams and proxies.
Support for streams (blobs).
Several databases supported at the back end: SQL Server, MySQL, PostgreSQL, Oracle, Firebird, etc. (using TMS Aurelius).
HTTP/HTTPS server architecture based on TMS Sparkle which provides:
- HTTP server based on the Windows http.sys stack;
- Built-in authentication mechanism with JWT (JSON Web Token) or Basic methods;
- Support for HTTP Secure (HTTPS);
- Kernel-mode caching and kernel-mode request queuing (less overhead in context switching);
- Multiple applications/processes can share (respond to) the same port (at different addresses/endpoints);
- Secure Sockets Layer (SSL) support in kernel-mode.

Overview

Features

In this section:

Getting Started

Service Operations

TMS Aurelius CRUD Endpoints

TXDataClient

JSON Format

Design-Time Components

XData Model

Server-Side Events

Authentication and Authorization

Other Tasks

Web Applications with TMS Web Core