Show/Hide Toolbars

TMS XData Documentation

Navigation: Basic XData Programming


Scroll Prev Top Next More

To create an XData server, you need to add a TXDataServerModule object to the Sparkle HTTP Server. As with any Sparkle module, it will have a base (root) URL associated with it, and it will respond to requests sent to any URL which matches the root URL of the module.


The TXDataServerModule is the main XData class, because it is the one which receives and handles all HTTP requests. So in a way, that is the class that implements the XData server. Although it is a very important class, its usage is very simple. You need to create the class using one of the overloaded constructors (TXDataServerModule is declared in unit XData.Server.Module):


constructor Create(const ABaseUrl: string); overload;
constructor Create(const ABaseUrl: string; AConnectionPool: IDBConnectionPool); overload;
constructor Create(const ABaseUrl: string; AConnectionPool: IDBConnectionPool; AModel: TXDataAureliusModel); overload;
constructor Create(const ABaseUrl: string; AConnection: IDBConnection); overload;
constructor Create(const ABaseUrl: string; AConnection: IDBConnection; AModel: TXDataAureliusModel); overload;


In summary, you must provide the base URL and optionally an IDBConnectionPool interface so that the server can retrieve IDBConnection interfaces to operate with the database (if database connectivity is desired). For example:


XDataServerModule := TXDataServerModule.Create('http://server:2001/tms/xdata', TDBConnectionPool.Create(50,
      function: IDBConnection
        MyDataModule: TMyDataModule;
        MyDataModule := TMyDataModule.Create(nil);
        Result := TFireDacConnectionAdapter.Create(MyDataModule.FDConnection1, MyDataModule);


The example above creates the server with the root URL "http://server:2001/tms/xdata" providing a connection pool of a maximum of 50 simultaneous connections. The database connection used will be a FireDac TFDConnection component named FDConnection1, declared in a data module named TMyDataModule. That is all you need to set up for your XData server to run and to expose your Aurelius objects.


The first overloaded constructor, used in the previous example, takes just two parameters: The base url and the connection pool. The other overloaded versions are just variations that provide different settings.


If you have multiple Aurelius mapping models in your application, you can optionally use an entity model different from default, or explicitly build an entity model and provide it in the constructor for specific mapping. This allows for better control which classes and mapping settings are available from the XData server. If the model is not provided, XData uses the default entity model which in turn uses the default Aurelius model. Note that the model passed to the constructor will not be owned by the server module and must be destroyed manually. For example, the following code creates a module using the "Sample" model:


XDataServerModule := TXDataServerModule.Create('http://server:2001/tms/xdata', MyConnectionPool, TXDataAureliusModel.Get('Sample'));


There are also versions of the Create constructor that receive an IDBConnection interface instead of an IDBConnectionPool. Those are easy-to-use variations that internally create a connection pool with a single connection (no simultaneous connections available). It is an easy approach for testing and debug purposes, but should not be used in production environments because performance might not be ideal.






property UserName: string

property Password: string

TXDataServerModule provides these properties to specify UserName and Password required by the server using Basic Authentication. By default, these values are empty which means no authentication is performed and any client can access server resources and operations. When basic authentication is used, be sure to use HTTP secure (HTTPS) if you do not want your user name or password to be retrieved by middle-man attacks. If you do not use it, both user name and password are transmitted in plain text in HTTP requests.


These properties provide a very limited basic authentication mechanism. For a more advanced variant, you should use the TMS Sparkle built-in Basic Authentication mechanism.

property AccessControlAllowOrigin: string

Specifies the accepted client hosts for which CORS will be enabled. If you want to accept any client connection, set this property value to '*'. This will enable CORS in the server including proper responses to preflighted requests.

property DefaultExpandLevel: integer

Defines the minimum level that associated entities will be expanded (included inline) in JSON responses. Default value is 0 meaning that all associated entities will be represented as references unless specified otherwise. Clients can override this value by using xdata-expand-level header.

property Events: TXDataModuleEvents

Container for server-side events.

property PutMode: TXDataPutMode

Defines how PUT will be implemented at server side with Aurelius: Either TXDataPutMode.Update or TXDataPutMode.Merge method (default). You will rarely need to change this property unless to ensure backward compatibility with older versions. This property value can be overridden in a specific request by using xdata-put-mode HTTP Request header.

property SerializeInstanceRef: TInstanceRefSerialization

Controls how instance reference ($ref) will appear in JSON response. Options are:


TInstanceRefSerialization.Always: $ref is always used if the same instance appears again in the JSON tree. This mode is more optimized for use with TXDataClient, and is the default option.


TInstanceRefSerialization.IfRecursive: $ref is only used if the instance appears as an associated object of itself. If the instance appears in a non-recursive way, $ref is not used and the instance is fully serialized inline instead. This mode is more suited for JavaScript and other non-Delphi clients so those clients do not need to resolve the $ref objects.


This property value can be overridden in a specific request by using xdata-serialize-instance-ref HTTP Request header.

property SerializeInstanceType: TInstanceTypeSerialization

Controls whenever the entity/object type appears in the JSON response (property annotation "xdata.type"). Options:


TInstanceTypeSerialization.Always: The xdata.type annotation always appears in JSON responses.


TInstanceTypeSerialization.IfNeeded: The xdata.type annotation is only present if the entity/object type is a descendant of the expected type. For example, suppose a GET request is performed in url Customers. For any entity in JSON that is of type Customer, the annotation will not present. If the entity in JSON is a descendant of Customer (e.g., DerivedCustomer) then xdata.type apppears. Basically, it means that xdata.type is implicit when absent and is of the expected type of the request/specification.


This property value can be overridden in a specific request by using xdata-serialize-instance-type HTTP Request header.

property UnknownMemberHandling: TUnknownMemberHandling

Defines server behavior when receiving JSON from the client with a property that is not known for that request. For example, JSON representing an entity with a property that does not belong to that entity. Options:


TUnknownMemberHandling.Error: An InvalidJsonProperty error is raised if JSON contains an invalid property. This is the default behavior.


TUnknownMemberHandling.Ignore: Invalid properties in JSON will be ignored and the request will be processed.

property EnableEntityKeyAsSegment: Boolean

When True, it's possible to address single entities by using the URL format "/entityset/id" - in addition to the default "/entityset(id)". Default is False.

property SwaggerOptions: TSwaggerOptions

property SwaggerUIOptions: TSwaggerUIOptions

Provide access to configure Swagger and SwaggerUI behavior. See more information at OpenAPI/Swagger Support.






procedure SetEntitySetPermissions(const EntitySetName: string; Permissions: TEntitySetPermissions)

Specify the permissions for a specified entity set.