Show / Hide Table of Contents

    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.

    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.

    Other Tasks

    How-tos and examples about basic tasks you can do with XData in code.

    Server-Side Events

    Events that can be used to implement additional server-side logic, customize XData behavior, among other tasks.

    Web Applications with TMS Web Core

    The TMS XData Web-Client Framework: using XData servers from TMS Web Core applications.

    Back to top TMS XData v4.17
    © 2002 - 2021 tmssoftware.com