Overview
TMS XData is a Delphi framework that allows you to create HTTP/HTTPS servers that expose data through REST/JSON.
By using the concept of Service Operations, you create server-side methods (business logic) that are mapped to endpoints in your API. Whenever an endpoint is requested, your method is executed. XData has a very high-level and smooth learning curve allowing you to build the service operations without having to worry about HTTP communication, HTTP methods, JSON handling, among other low-level mechanisms. You just declare your methods using regular Delphi types, tag them with attributes to properly bind the endpoints to it, define authorization and authentication, multitenancy information, and everything is done automatically, including full Swagger documentation output.
It is also optionally integrated with TMS Aurelius ORM in a way that creating automatic CRUD endpoints based on applications with existing Aurelius mappings are just a matter of a few lines of code. For the automatic CRUD endpoints XData defines URL conventions for adressing resources, and it specifies the JSON format of message payloads. It is inspired 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 supports Delphi XE2 and up.
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.
In this section:
Getting Started
Getting your first XData server and client applications running.
Service Operations
How to implement and use service operations to add business logic to your server and invoke it from clients.
TMS Aurelius CRUD Endpoints
CRUD endpoints defined by XData for applications using TMS Aurelius.
TXDataClient
Using TXDataClient object to send and receive objects to/from a XData server in a straightforward way.
JSON Format
XData representation of different structures in JSON format.
Design-Time Components
Overview about XData components for design-time usage.
XData Model
TXDataAureliusModel: description of the available service operations and entities published from the CRUD endpoints.
Server-Side Events
Events that can be used to implement additional server-side logic, customize XData behavior, among other tasks.
Authentication and Authorization
How to implement authentication and authorization to protect your API from unauthorized access.
OpenAPI Support
Explains full XData support for OpenAPI and related tools like SwaggerUI and Redoc.
OpenAPI Importer
Generating client for 3rd party APIs using the OpenAPI importer.
Other Tasks
How-tos and examples about basic tasks you can do with XData in code.
Web Applications with TMS Web Core
The TMS XData Web-Client Framework: using XData servers from TMS Web Core applications.