Delphi REST Servers and 3rd party Applications

Question

I would like to port an existing SOAP server to a REST framework in Delphi and I would like the REST server to be usable by 3rd party applications written in languages other than Delphi. What sort of design considerations would be important. For example

1. If I select compression of data when using the Delphi REST Server Wizard will the server still be usable by 3rd party applications or do I need to compress data structures myself and use string parameters to pass these structures to and from the REST server?

2. Should I avoid using proprietary Delphi parameters like TDateTime and use formatted date time strings instead?

3. Should I use JSON for all server communication, i.e. all data structures encoded in JSON, or maybe compressed JSON.

Answer 1

Some points I would recommend to consider.

1. Use interface to define the service endpoints - just like with SOAP. Not a RAD-oriented approach, nor an attribute + methods approach.

2. Use ISO-8601 JSON strings for date/time, or Unix TimeStamp (integer since 1970 in second or millisecond resolutions) - never TDateTime/OLE float value. Those two first formats are recognized by all clients, including javascript.

3. Rely on the transport layer (i.e. HTTP) for compression. I usually setup a nginx reverse proxy, running on Linux, with gzip compression and HTTPS via Let's Encrypt, and let the Windows/Delphi server serve raw JSON over HTTP, with proper isolation to the Internet. Don't use binary layouts (like ProtoBuf), if you want the clients to be easy to work with. HTTPS+JSON is fast enough for 90% of the usecases. Just use proper paging if necessary.

4. If you want to reduce the payload size, consider using an alternate endpoint using an JSON array of values instead of a JSON object. The problem with it is that it will be less maintainable: it is difficult to make this evolve. Some frameworks (like our mORMot) allow both layouts.

5. Prepare for versioning from the first published API. The easiest is to define an interface per revision, accessible from server.com/v1 then server.com/v2 URI.

6. Don't leak your business model (i.e. your raw data structures, e.g. your SQL tables). Define DTOs for the REST services, as a cut-down version of your data structures. Those DTOs should be client-centric (what a client wants in a given usecase?), not server-centric (which data can I publish?). Use an interface per use-case. For instance, you may have several "Users" endpoints, depending on the context used. A single REST server to rule them all is difficult to maintain and use.

7. Your REST framework should be able to generate client code and documentation for the clients. Swagger helps.

8. Prepare to be able to switch to FPC for the server part. Its Linux/BSD and ARM/AARCH64 support is brilliant, so it may enhance long-term maintenance of your refactored server code.

9. Consider designing state-of-the hard endpoints. Defining e.g. at least MicroServices, and even Domain-Driven-Design if your project meets its requirements. At least look at these ways of designing APIs. Naive REST approach is easy to start from the server point of view, but difficult to consume and to evolve. Never map the DB directly!

10. Take into account the multi-thread abilities of the REST server. Scaling comes by leveraging the multi-threading of the HTTP server and the business logic.

11. Consider publishing WebSockets endpoints for real-time notification. End users are now used to have very responsive applications, with real-time updates on screen.

12. Use testing from the ground up. Using interface would help mocking/stubbing your services.

Of course, our Open Source mORMot framework was designed for this kind of process. Just google for alternatives.