Aloe XWS

Aloe XWS makes it easy for Xojo developers to create
Web services / APIs, microservices, middleware, and more.

Aloe XWS is an open source Xojo module that has been specifically designed for developing Web services, APIs, microservices, and middleware.

Aloe XWS:
• Leverages the Xojo Web framework.
• Includes classes that represent HTTP requests and responses.
• Provides easy access to the important attributes of an HTTP request, including its body, content type, GET (URL) parameters, headers, method (GET, POST, etc), path, POST fields, and the client's remote address.
• Makes it easy to return an HTTP response by providing methods for specifying the response's content, content type, headers, and status code.
• Is being provided under an MIT License (MIT).

With Aloe XWS, "Hello World" is a single line of code.


Here's an example of routing requests in Aloe XWS.


Aloe XWS v2019r2
Released on 2019-10-11.
Resolves and eliminates deprecation warnings that were introduced in Xojo 2019 R2.

Aloe XWS v2019r1
Released on 2019-10-09.
This is the initial public release of Aloe XWS.
Includes a demo Xojo Web project with the AloeXWS 2019r1 module, a REST API demo module, a SQLite database for use with the API, and example API calls.

The best way to get started with Aloe XWS is to explore the demo project, which includes the Aloe XWS module, and a module that is a basic REST API.

After downloading the Aloe XWS zip file, unzip it, and copy the example SQLite database (drummers.sqlite) to your desktop. If you'd like to use a different location, you can do so by adjusting the "DatabaseFile" variable in the RESTAPIDemo module > RequestHandler class > DatabasePrepare method.

Next, run the Xojo project, and make some API calls. Example cURL API calls are included in the zip file, and if you happen to be a Paw user, there's a Paw file that includes those same calls.

I encourage you to explore both the demo project and the Aloe XWS module. Here a few things worth noting.

• The Aloe XWS module includes three classes: Application, Request, and Response. The Application class is a subclass of the Xojo WebApplication class. The Request class is used to handle incoming HTTP requests. The Response class is used to return an HTTP response.

• The App is an instance of AloeXWS.Application. Remember that this is a subclass of the Xojo's WebApplication class (which is essentially the Web framework).

• All incoming HTTP requests are handled by the App.HandleRequest event handler, and two parameters, Request and Response, are automatically passed to the event handler. The HTTP request is modeled via an instance of the AloeXWS.Request class. The request is paired with an instance of the AloeXWS.Response class.

• Notice that in the App's HandleRequest method, the HTTP request is evaluated and routed accordingly. If the request is being made for the API demo ( which is determined by looking at the requested path and looking for "/apidemo" ), then the request and response instances are passed to an instance of the RESTAPIDemo.RequestHandler class for processing.

• The RESTAPIDemo module is a very basic example of how you can implement a RESTful API. This basic API provides create, read, update, and delete operations against a SQLite database.

• Notice that the Xojo Web framework's Session and WebPage1 instances are not used by the demo app or by Aloe XWS in general. However, those instances are required by the Web framework, so they cannot be removed. (In the demo project, you can find them in the "Unused" folder.)

Hopefully, this has helped you to get started and acquainted with Aloe XWS.

Happy coding!

What does "XWS" stand for?
It's short for "Xojo Web Service."

How is Aloe XWS different from Aloe Express?
It's designed specifically for developing Web services / APIs, microservices, and middleware. It's not something you'll want to use to develop Web apps or public-facing sites. Also, XWS leverages the Xojo Web framework, and it does so by subclassing the Xojo WebApplication class. As a result, it can only be used with the Xojo Web framework. You cannot drop it into a Xojo desktop or console project.

Is XWS a direct replacement for Aloe Express?
No. Aloe XWS is an entirely new module, and it only works with Xojo Web projects. Depending on how you're using Aloe Express, migrating an existing app to Aloe XWS might take some work.

What was the motivation behind developing Aloe XWS?
I found that I wasn't using the majority of the features that had been added to Aloe Express over the past few years. I wanted a more streamlined version of Aloe to work with, one that made the type of development that I do (which primarily involves Web services, middleware, etc) easier. So I started with a blank slate, and developed XWS.

Has Aloe XWS been thoroughly tested?
Yes. I've had Aloe XWS-based solutions running in production since Q1 of 2019.

What do I need in order to use Aloe XWS?
To compile an app that uses XWS, you'll need a Xojo license that supports compiling Xojo Web apps - either a Xojo Web, Xojo Pro, or Pro Plus license.

What support options are available?
If you have a general question about Aloe XWS, you might want to consider posting it to the Xojo Forum. If you need my help, I do provide technical support directly, starting at $150 / hour, with a one hour minimum. If you'd like to schedule a support session, email me at

Do you anticipate problems with XWS when the new Xojo Web framework is released?
It's hard to say with absolute certainty, but I don't think there will be any major problems with it.

What's the future of Aloe Express?
I have no plans to release upgrades to Aloe Express, so Aloe Express v4.1.1 is the last "official" version of Aloe Express. If the community stills find value in Aloe Express, then my hope is that other developers will continue to maintain and enhance it.

Is Aloe Express still available for download?
Yes. Aloe Express, and the various add-ons, are still available here.

What is Aloe for PHP?
Aloe for PHP is a microframework that I've designed using the same principles that I used with Aloe XWS. It gives developers everything they need to resolve inbound HTTP requests and send back responses. It's very simple, and it never gets in your way. I've been using Aloe for PHP in various forms for more than a year now, and announced it several months ago. I'm planning to release it in Q4 of 2019.

Who developed AloeXWS?
Aloe XWS was developed by Tim Dietrich, a software developer that creates custom Web applications, APIs, and middleware.

Issue w/ Copying AloeXWS Module into New Xojo Projects
Starting with Xojo 2019 R2, when copying the AloeXWS module into a new Xojo project file, the module's Application class is not copied to the destination project. If you are starting a new Xojo project and want to use Aloe XWS, I suggest that you either start with the demo project and remove what you don't need, or take the time to manually recreate the Application class in your new project file.

Looking for Aloe Express? Click here.

© 2020 Tim Dietrich.