This article examines Xojo’s capabilities by building a simple web API service. You will learn to handle different HTTP methods, manage requests, and send meaningful responses. Xojo’s simplicity makes it an excellent choice for experienced developers transitioning from other languages, as well as those familiar with its user-friendly language.

Foundation: The HandleURL Function

Defining API Endpoints for GET Requests

GET requests are primarily used to retrieve data. To handle these requests effectively, let’s see how to define API endpoints that correspond to specific data or actions in the following code example:

If request.Method = "GET" Then
  Select Case request.Path
  Case "time"
    Var currentTime As String = DateTime.Now.ToString("yyyy-MM-dd HH:mm:ss")
    response.Write("{""message"": """ + currentTime + """}")
    response.Status = 200
    Return True
  Case "hello"
    response.Write("{""message"": ""Hello, World!""}")
    response.Status = 200
    Return True
  End Select
End If

Here, we define two endpoints: /time and /hello.

A GET request to /time will return the current date and time in JSON format, while a request to /hello will return a friendly “Hello, World!” greeting.

The response.Status is set to 200, indicating a successful response. Learn more here about HTTP status codes.

Defining API Endpoints for POST Requests

While GET requests primarily retrieve data, POST requests submit data to the API for processing. Consider submitting a form online – you are sending data to the server via a POST request.

If request.Method = "POST" Then
  Select Case request.Path
  Case "some-data"
    Try
      Var jReceivedData As New JSONItem(request.Body)
      Response.Write(jReceivedData.ToString)
      Response.Status = 200
      Return True
    Catch e As JSONException
      response.Write("{""error"": ""Internal Server Error""}")
      response.Status = 500
      Return True
    End Try
  End Select
End If

In this example, a POST request to the /some-data endpoint expects to receive JSON data (request.Body) for processing.

If the data is successfully parsed, the API responds with the received data.

Otherwise, an error status and message are returned to the client.

Bringing it all Together

Now that you know how to manage “GET” and “POST” requests, you can start building more complex APIs, with different endpoints available for different methods. To further illustrate API endpoint development, consider the following detailed code example that can be used as template:

Function HandleURL(request As WebRequest, response As WebResponse) Handles HandleURL as Boolean
  response.MIMEType = "application/json"
  
  Try
    Select Case request.Method
    Case "GET"
      
      Select Case request.Path
      Case "time"
        Var currentTime As String = DateTime.Now.ToString("yyyy-MM-dd HH:mm:ss")
        response.Write("{""message"": """ + currentTime + """}")
        response.Status = 200
        Return True
      Case "hello"
        response.Write("{""message"": ""Hello, World!""}")
        response.Status = 200
        Return True
      Else
        response.Write("{""error"": ""Not Found""}")
        response.Status = 404
        Return True
      End Select
      
    Case "POST"
      
      Select Case request.Path
      Case "some-data"
        Try
          Var jReceivedData As New JSONItem(request.Body)
          Response.Write(jReceivedData.ToString)
          Response.Status = 200
          Return True
        Catch e As JSONException
          response.Write("{""error"": ""Internal Server Error""}")
          response.Status = 500
          Return True
        End Try
      Else
        response.Write("{""error"": ""Not Found""}")
        response.Status = 404
        Return True
      End Select
      
    End Select
    
  Catch e As RuntimeException
    response.Write("{""error"": ""Internal Server Error""}")
    response.Status = 500
    Return True
  End Try
  
  response.Write("{""error"": ""Not Found""}")
  response.Status = 404
  Return True
  
End Function

Small note: observe the start line within the HandleURL function.

response.MIMEType = "application/json"

This line of code informs the client (browser, application) that the API service is responding using the JSON format. Setting the MIMEType to “application/json” is best practice and helps prevent any potential parsing errors on the client side.

Next Steps

You might notice that some code is repeating itself (hint: the error responses), so a good idea would be to create a helper method that deals with this particular type of code repetition. Additionally, consider moving the code from the HandleURL function to a separate method that is then invoked within the HandleURL function for improved organization. This restructuring will enhance code organization, making it easier to maintain, read, and improve the efficiency of the program.

P.S.: You should also check the article about microservices and their purpose to get a better idea of what kind of API interfaces you can create.

Gabriel is a digital marketing enthusiast who loves coding with Xojo to create cool software tools for any platform. He is always eager to learn and share new ideas!

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

iOS Notifications

Xojo Cloud can function as an Apple Push Notification system (APNs) for handling iOS push notifications. This works with Xojo and non-Xojo iOS apps. All Xojo Cloud servers are pre-configured to send remote notifications. Unlike many other cloud hosts, there is no extra charge for this feature nor is there any limit as to how many notifications you can send.

To send remote notifications from your iOS app you’ll need to go to the Apple Developer website to do these tasks:

1. Add the Push Notifications feature to the App ID.
2. Generate an Apple Push Services certificate.

In Xojo you need to enable the Remote Notifications entitlement for your app in the Capabilities section of the iOS Build Settings Advanced tab.

The final step is to upload your Push Services certificate using the Xojo Cloud control panel.

With super-easy access and no limits for notifications, Xojo Cloud can serve as a great APNs for handling your iOS notification needs.

Database Servers

Most desktop apps use a database of some kind and many are client/server database apps that talk directly to the database server. With Xojo Cloud you can host PostgreSQL or MariaDB/MySQL database servers and connect to them using an SSH tunnel for security purposes.

Setting up a database server on your Xojo Cloud is as easy as checking a box in the control panel.

You can turn on PostgreSQL or MySQL/MariaDB. If your Xojo Cloud server is large enough you could even do both.

If you want to access a database on Xojo Cloud from a desktop app, you will have to enable the SSH Tunnel and then connect to the tunnel from the computer. An SSH tunnel is a secure connection between your computer and another (in this case your Xojo Cloud server) which is used for transmitting data on a specific port. In essence, it creates a private connection through the internet which allows you to see into your server on the other end and connect to a particular service there.

To create a tunnel between a computer and your Xojo Cloud server, you first need to turn on the tunnel capability on your Xojo Cloud server. Go to your control panel and click the “SSH Tunnel” checkbox. You will be presented with a generated username and a password which you will use later for establishing the connection.

On macOS and Linux, you can use a terminal command to access the tunnel (replace username and ipaddress as appropriate; you’ll be prompted for the password).

Use this command to tunnel to PostgreSQL:

ssh -L 5432:localhost:5432 username@ipaddress -N

Use this command to tunnel to MySQL:

ssh -L 3306:localhost:3306 username@ipaddress -N

If you are using Windows, you will need to use an external app such as PuTTY. There are a number of tutorials available on the internet, just put “putty ssh tunnel” into your favorite search engine.

With the tunnel in place you connect to the database as if it were local to the computer. This works with anything, not just Xojo apps.

SFTP

Xojo Cloud offers SFTP (Secure File Transfer Protocol) for file transfer. SFTP is a secure variant of FTP which transmits files over the internet using strong encryption. That way you don’t have to worry about anyone intercepting your username and password or your files as they’re sent to or from your server.

When choosing a client, keep in mind that SFTP is different than FTPS or FTP w/ SSL. They are not interchangeable with one another.

Once you enable SFTP in the Control Panel, you’ll be presented with a dialog showing a generated username and password.

You can now connect using your favorite SFTP client. If you don’t have one, there are a number of free and paid options available including:

• ForkLift
• Transmit
• FileZilla
• CyberDuck

Having a place to store files online is always handy and can be useful when needing to share files with others without having to rely on services such as DropBox.

Web Services

OK, a web service is technically a Xojo web app but it is really an API that is meant to be used by other apps, often desktop or mobile apps. Since a web service doesn’t have any actual UI, you don’t really need to learn how to use the majority of the Xojo Web framework.

Instead you basically add code to the App.HandleURL event to route web service API calls to do specific tasks and then return the results, usually as JSON for the client app to handle.

A web service can be a great way to consolidate code that will be used by desktop and mobile apps, for example.

For example, you could create a Web Service that talks to a database server (such as one of the ones available in Xojo Cloud itself). Your Desktop and Mobile apps can use the same web service to work with the database. All your database-specific code lives in the web service and the client apps make requests and display results.

This is a very common design pattern these days and is a necessary one if you want a mobile app to talk to a database server.

If you want to learn more about web services, here’s a fun webinar to check out:

Learn more about Xojo Cloud today. Xojo Cloud servers start at $49/month, custom servers with more RAM, storage, and virtual CPUs are available. The best way to host your Xojo web apps is so much more than just hosting web apps!

Paul learned to program in BASIC at age 13 and has programmed in more languages than he remembers, with Xojo being an obvious favorite. When not working on Xojo, you can find him talking about retrocomputing at Goto 10 and on Mastodon @lefebvre@hachyderm.io.

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

RESTy uses the URLConnection class to send a request to a web service and get a result. If the result is text (JSON, for example) it displays in the Response tab. Here, I am calling the Eddie’s Electronics web service to return a list of all the customers by specifying the URL and clicking the Fetch button:

For other data (binary data such as pictures) you can use the Fetch to File button to save the request to a file.

The Authentication tab is used to provide Basic Authentication should the web service require it.

The Request Content tab can be used to provide Content data that the request might need. For example, the Eddie’s Electronics web service also lets you request the details for a specific customer by providing simple JSON containing the customer ID. To try this using RESTy app:

1. Click on the Request Content Tab.
2. To indicate the customer you wish to retrieve, enter the following JSON into the field on that tab: {"ID": 10039}
3. Select POST from the Send Method popup menu.
4. In the URL field, enter: https://eews-demos.xojo.com/GetCustomer
5. Press the Fetch button.

If you have entered everything correctly, will see the data for Caleb Horn in JSON format:

And to see the JSON formatted nicely, click the Format JSON button:

This will let you you explore calling various REST API services. You can explore the source code to see how it uses URLConnection to do so.

To be sure, RESTy is very basic, but you have the source code so you and add features to it and modify it for your own testing needs.

I did some research and found that Amazon provides a service that does exactly what the client was asking for. The service, called Amazon Translate, is available as one of many services that are available through Amazon Web Services.

In this post, I’ll walk you through the process of getting signed up for Amazon Translate, and then share some code that you can use to add language translation to your own Xojo projects. We’ll use the MBS Xojo CURL Plugin, which makes calling the Amazon Translate API easy. But first, let’s learn a little about Amazon Translate.

Amazon Translate

Amazon Translate is an API that can be used to translate text on demand. You send it text in a “source language,” tell the API what that source language is, as well as the “target language” that you want the text translated to. The API responds with the translated text.

Amazon Translate uses machine learning and neural networks that have been designed specifically for language translation. When performing a translation, the service reads the text one sentence at a time, and reads each word individually, to determine the meaning of a sentence. In other words, the service doesn’t just translate words. Instead, it’s acting as an interpreter. This results in translations that are extremely accurate.

In order to use Amazon Translate, you’ll need an AWS account. If you already have an AWS account, log into the account.

Next, you’ll need to create an “Identity and Access Management” (IAM) user. To do so, under Services, select “IAM” (which can be found in the “Security, Identity, & Compliance” category). This will present you with the IAM Dashboard.

Under Groups, create a new group and give it a recognizable name. For example, you might call the group “translate.” As you are creating the group, give it the “TranslateFullAccess” permission.

Next, create an IAM user. Under Users, click the “Add user” button. Give the user a name such as “XojoTranslater.” For the “AWS access type” be sure to select “Programmatic access.” Add the user to the “translate” group that you created above. There’s no need to assign any tags to the user, so you can skip that step.

And finally, create an Access key for the user. Be sure to make note of both the “Access key ID” and “Secret access key” values that are automatically assigned. You’ll need these in order to make API calls.

The MBS Xojo CURL Plugin

If you don’t already have the MBS Xojo CURL Plugin, download it and install it. To install the plugin, simply drag it into the Xojo “Plugins” folder.

The project will work with an unlicensed version of the MBS Xojo CURL Plugin. In this case, you’ll occasionally see a popup message reminding you to purchase a license. However, I highly encourage you to purchase a license. You can license the plugin individually, or as part of the MBS Complete plugin bundle.

The Xojo Example Project

To demonstrate the Amazon Translate service, I’ve put together an example Xojo desktop project (project file). Before running the application, be sure to set the three App-level properties: AWSAccessKeyId, AWSSecretAccessKey, and the AWSRegion. For the AWSAccessKeyId and AWSSecretAccessKey properties, use the values that you set when you created the Access key for the user. For the AWSRegion, refer to this and use the value that makes the most sense for you.

Once you’ve configured the app, run it, and it will look something like this.

The Xojo Code

Let’s take a look at some of the code.

The AWSTranslator class is a subclass of the CURLSMBS class. The class does two important things: It provides access to a list of the languages that are supported, and provides a method for calling the Amazon Translate API.

The “Languages” property is a dictionary that you can use to get the names of the languages that Amazon Translate supports and the corresponding language codes. The example app uses this dictionary to populate the “Translate From” (SourcePopupMenu) and “Translate To” (TargetPopupMenu) popup menus.

The Translate method creates the payload that gets sent to the Amazon Translate API, and sets special HTTP headers that are needed in order to call the API. But most importantly, it uses the CURLSMBS class’s “SetupAWS” method to configure the CURL instance so that all of the steps that are required to “sign” the API request are done automatically. This is an amazingly convenient function of the MBS Xojo CURL Plugin. You can get a sense of what’s involved in signing the request here.

To translate text using the AWSTranslator class, you create an instance, configure it with your IAM credentials and AWS region, pass it the source language text, the source language code, and the target language code. In the example app, this all handled in the Window1.Translate method. The values are pulled from the App-level properties, as well as the various window controls. Finally, you call the AWSTranslator instance’s Translate method. If the translation is successful, the translated text will be available via the TranslatedText property. If any errors occur, the ErrorType and ErrorMessage properties will be set.

The “Estimated Translation Cost” is calculated whenever the Source Text changes. The value is calculated by taking the length (number of characters) of the Source Text and multiplying it by 0.000015 (the average cost for translating a single character).

Wrapping Up

I’ve been amazed at the speed and accuracy of the Amazon Translate service. And after developing the AWSTranslator class, I was able to quickly and easily add language translation to my client’s middleware app.

I hope you’re equally impressed by the Amazon Translate service, and that you find the AWSTranslator class to be helpful in your own Xojo projects.

Tim Dietrich is a custom software developer based in Richmond, Virginia. To learn more, visit: https://timdietrich.me

Situations Where A Client/Server RDBMS May Work Better

Client/Server Applications

If there are many client programs sending SQL to the same database over a network, then use a client/server database engine instead of SQLite. SQLite will work over a network filesystem, but because of the latency associated with most network filesystems, performance will not be great. Also, file locking logic is buggy in many network filesystem implementations (on both Unix and Windows). If file locking does not work correctly, two or more clients might try to modify the same part of the same database at the same time, resulting in corruption. Because this problem results from bugs in the underlying filesystem implementation, there is nothing SQLite can do to prevent it.

A good rule of thumb is to avoid using SQLite in situations where the same database will be accessed directly (without an intervening application server) and simultaneously from many computers over a network.

So what are your options when you want to share your database?

If you want to stick with SQLite then you’ll need to put something in front of it that can handle requests from multiple client apps. The most obvious solution is to create a web service by using a web app with WebApplication.HandleURL (or HandleSpecialURL). The web app can accept requests from multiple client apps (or any type — desktop, web, mobile, etc.), fetch the data requested from the SQLite database and then send it back as JSON. This works because the web app is the only app that is connected to the SQLite database.

The Eddie’s Electronics Web Service sample shows you how you might set this up: Examples/Communication/Web Services/EddiesWebService

Another option for setting up your own database web service is to use the Aloe open-source project, which gives you a robust framework for building web services.

To learn more about database web services, check out the Making Database Web Services video.

By the way, this is also why a regular web app can safely use SQLite with multiple users — the web app manages the multiple users but is the only app that is connected to the SQLite database.

If you want to stick with SQLite but would rather not create a web service, another option to consider is to use a product that puts a database server around SQLite. CubeSQL and Valentina have products available that can do this.

Your final option is to switch to an actual database server. PostgreSQL and MySQL are popular alternatives.

In this second post on the topic we will focus on the client side desktop app that will be in charge of creating the requests using the web service published API. This desktop app will send new data to our web server app so it can be added to the backend database.

The main topics are:

• Creating a subclass from the URLConnection class
• Dealing with the data received from the server as result for the request
• Encoding a JSONItem for sending data to the web service

As stated in the previous entry, the example doesn’t include the normal (and recommended) verifications on the data provided and received or the check on possible errors; we are only focused on the main topic.

Creating an URLConnection subclass

Let’s start by creating a new desktop project. Add a new Class using Insert > Class and use the Inspector to assign URLConnection as the Super Data Type as shown in the picture:

With the just added class still selected in the Navigator (the leftmost column in the IDE Window), add a new property to it (Insert > Property). We will use this property so it points to a DesktopListBox in our user interface, and so we can update it with the data received from our web service. With the just added property still selected, use the Inspector to set its Data Type and Name (text label used from our code to refer to such property) as follows:

• Name: List
• Type: DesktopListBox
• Scope: Private

Note that we set the scope as Private. This means that this property can be accessed only from the instances of the class, and not those that are created from other data types or even those created as subclasses from this class.

URLConnection: Asynchronous communications

Why would we want to maintain a reference to a ListBox control in our URLConnection class? As with any kind of problem, we can take several approaches in order to solve it. In this case, is a very convenient way to get a reference to the control we want to update as we will be using the URLConnection asynchronously.

Once we call the request against our web service, the execution of the app will not be paused until we receive a response, this allows the user to do other operations if they want. In this case the class instance, via the ContentReceived event, will be responsible to receive the new data from the web service, so we can use it.

In fact, this is our next step. With our URLConnection subclass still selected in the Navigator, add a new Event Handler to it (Insert > Event Handler…). In the resulting window, choose the PageReceived option from the list and confirm the selection, so the event will be added to the class under the Event Handlers section.

Now, with the just added Event Handler still selected, write the following snippet of code in the associated Code Editor:

#Pragma Unused url

If HTTPStatus = 200 Then // We received an OK as the status for our request
  If Content.Length <> 0 Then // And we have data to process as part of the reply
    List.RemoveAllRows // So we delete previous existing entries in the associated ListBox Control
    content = content.DefineEncoding(Encodings.UTF8) // We set the encoding for the received data
    
    Var items As Dictionary = ParseJSON(content) // And proceed to create a new dictionary from the received data in JSON format
    items = items.Value("AllAlbums") // We get all the items for the key 'AllAlbums'…
    For Each item As DictionaryEntry In items // …iterating on them…
      Dim tempDict As Dictionary = item.Value // …and retrieving the dictionary (JSON item) for it…
      Dim title As String = tempDict.Value("title") // …so we finally access the desired value
      list.AddRow title
    Next
  End If
End If

The code is commented so you can follow what happens in each line in the process; but it is worth it to point out that the ContentReceived event gives us all the parameters we need in order to work with the data sent from the web service:

• URL: The URL returned as the reply for our request
• HTTPStatus: The HTTP status code that you should read to verify the success of the request
• Content: This is a String that can contain the data associated with the reply.

In addition, you can also add an extra event handler to our subclass: Error. This will be fired when an error is produced while dealing with requests sent from the instance.

With the events and property already set, it is time to add a couple of methods in charge of commanding our URLConnection subclass to launch the requests. For our example, those method names are directly related to the operations we want to do on the web service API created on the first part of this tutorial.

So, with our URLConnection class still selected in the Navigator, add a new method (Insert > Method), using the following data in the associated Inspector. This is the method in charge of requesting our web service for the name of all the available albums. Of course, we expect to receive the reply through the ContentReceived event:

• Method Name: GetRequest
• Parameters: theList As DesktopListBox, theURL as String
• Scope: Public

As you can see, this method expects to receive the reference to a DesktopoListBox control, and the text to the URL that should be the end point of our web service. Now put the following code in the associated Code Editor for the just added Method:

List = theList
self.send("GET", theURL)

Simple, isn’t? As you can see, we save the reference to the DesktopListBox control in the instance property so we can use it later for updating its contents with the received data. Then we use the Send method from the class with the GET verb and the URL where our web service should be listening for incoming requests. As previously stated, this is an async operation, so we will let our object to react through the ContentReceived or Error events.

URLConnection: Sending data as part of a request

Add a new method to the subclass, using the following values in the resulting Inspector. This is the method allowing us to send data to the web service so they can be added to the backend database:

• Method Name: SendItem
• Parameters: Item As JSONItem, theURL As String
• Scope: Public

This time, the method expects to receive and JSONItem object (pointed via the variable Item) and a String instance that should be the web service endpoint URL. Put the following code in the associated Code Editor for the method:

Self.SetRequestContent( item.ToString, "application/json" )
self.Send("POST", theURL)

The URLConnection instances allow us to associate additional information (data) for a request sending, in addition to those added through the HTTP headers (Head), using for that the SetRequestContent method. This method expects two parameters: a String with the real data to attach, and the definition of the type of data we are sending (this is, the MIME Type) as a String instance.

Finally, we launch the request in the second line of code, using for that the URL assigned to the theURL parameter and using the verb POST.

Designing the User Interface

We have already finished all the logic behind our example app, via our URLConnection subclass. So now it’s time to design a minimal user interface so we can verify the correct functionality of our client agains the web service.

Select the Window1 object and add the required control so it looks like the one displayed here (from top to bottom): a DesktopListBox, a couple of DesktopTextFields in addition of two DesktopLabels, and two DesktopPushButtons named “Request” and “Send”.

Next, add an instance of the created URLConnection subclass. For that, simply drag the created subclass from the Project Browser to the Window Layout Editor and a new instance will be added to the Tray in the lower section of the Editor, as shown in the following picture:

The only code present in the user interface is the one that we will add to both PushButtons. Double click the one labeled “Request”, and add the following line of code to its Pressed Event Handler:

MyConnection1.getRequest(AlbumListbox, "http://127.0.0.1:8081/GetAll")

It calls the getRequest method on the instance based on our subclass, sending as parameters the control “ListBox1” and the text for the (local) URL where the web service should be listening.

Double click the PushButton labeled “Send” in order to add the Pressed Event Handler and write the following fragment of code into the associated Code Editor:

Var d As New Dictionary
d.Value("Title") = TitleField.Text
d.value("ArtistId") = ArtistIDField.Text
Var item As New JSONItem
item.Value("newAlbum") = d

MyConnection1.sendItem(item,"http://127.0.0.1:8081/AddAlbum")

As you can see, there is nothing magic in it. We simply create a new dictionary using the keys expected from our web server to access the underlaying data for the record. In addition, you can see how easy it is to create a new JSONItem from a Dictionary!

Then, we simply call the sendItem method on our URLConnection subclass instance, passing along the expected parameters: a JSONItem instance and the web service endpoint URL that should include the method we want to call in the remote API.

Ready to listen for your requests!

We have finished our client app! Launch the web service created in the first part of the tutorial (make sure it is listening using the port 8081). Then, run the desktop client app and push the buttons for “sending” or “requesting” the information. You will see how with the request you’ll receive all the albums available in the example database, while with the “Send” button you’ll be able to add new records to the database with the data provided in both TextFields.

In conclusion, Xojo allows us to create both the backend and the multiplatform clients in record time and in a really easy way! Obviously, the examples used in these two articles are not, by far, complete solutions you can use “As Is”, but they give the basics you can use to construct more robust and complete solutions for your own needs.

Javier Rodri­guez has been the Xojo Spanish Evangelist since 2008, he’s also a Developer, Consultant and Trainer who has be using Xojo since 1998. He manages AprendeXojo.com and is the developer behind the GuancheMOS plug-in for Xojo Developers, Markdown Parser for Xojo, HTMLColorizer for Xojo and the Snippery app, among others

*Read this post in Spanish

In this two part tutorial you will see how easy it is to create a basic web service using Xojo Web. In the second part, we will create a Desktop client to talk with the web service (you may want to add iOS to the list).

Before we start, let me point out that this tutorial leaves out some details related to error checking, validation, data sanitizing and other specifics related to inputs and outputs in order to focus on the central topic. In addition, if you want to follow and reproduce the steps of this tutorial, then you need to download the Chinook Database, named “test.sqlite” in this tutorial.

Services in practice

Let’s start creating a web service! Open the Xojo IDE, create a new Web project, and name it WebService. The first thing you’ll notice is that Xojo adds a web page to the project by default – even when our web service does not display a UI. The good part is that you can mix both worlds, adding the webservice part to your regular Web app!.

In fact this tutorial will put all the logic in the App object. Start by adding a new property in charge of the reference to our SQLite database (of course, it will work also with PostgreSQL or MySQL engines). Select the App object from the Navigator (the left panel in the Xojo IDE), choosing the Insert > Property option from the contextual menu. With the new property selected, go to the Inspector to set the name, type and scope using these values:

• Name: Database
• Type: SQLiteDatabase
• Scope: Private

Next, we will add the Chinook Database to the Resources folder of our Web App. For that, select the deployment target under Build Settings (it can be macOS, Windows, Linux or Xojo Cloud, for example), and add a Copy Files build step to it. In the resulting Editor, add the Chinook database SQLite file and make sure you select the “Resources Folder” entry in the Destination popup menu, and the “Both” entry in the Applies To popup menu.

Now is time to create a new SQLiteDatabase instance and assign it to this property, so it will point to the SQLite database file when the app is running. For that, make sure the App object is selected and add the Opening Event Handler to it using the Insert > Event option. Write the following code in the resulting Code Editor:

#Pragma Unused args

Var f As FolderItem = SpecialFolder.Resource("Chinook_Sqlite.sqlite")

If f.Exists Then
  
  Try
    database = New SQLiteDatabase
    database.DatabaseFile = f
    
    Call database.Connect
  Catch e As DatabaseException
    MessageBox "Error connecting to the database"
  End Try
  
End If

As you can see, it is pretty much the same code we already use when creating SQLiteDatabase instances in our Desktop apps, linking to our SQLite database file and stablishing the connection so we can operate with the database engine from our app.

All the Magic of HandleURL

Xojo Web projects offer a simple way to handle the request received. It is using the HandleURL event. This is the one that fires every time a client app (it may be a Web Browser, desktop or mobile app) connects to the URL associated with the IP address and port combination that is listening for incoming requests.

For example, a valid URL that can be trapped and processed by HandleURL is:

http://www.nice-web-domain.com/getCustomers

Where getCustomers is in this case one of our API methods.

So, with the App object selectd, choose Insert > Event in order to add the HandleURL event.

As we will see, once the event has been added to a web app, it will receive the Request parameter (a WebRequest data type), waiting from us to send back a Boolean value as response: True to process the request or False (the default value) to ignore the response.

Introducing Request, where the information lives!

In fact, we will find in the Request object everything we need to process and (if it is the case) respond to the request from our Web service. For example, through we can get the interesting component from the Path property. If we consider this URL:

http://www.nice-web-domain.com/getCustomers?spain

The Request.Path property will return the getCustomers string; so our web service can process it acordingly from this point on.

Receiving and Sending JSON data

In order to keep this tutorial brief, our web API only has two methods in it: GetAll and AddAlbum. Using the first one, the client app will get the album name in the database wrapped in JSON format. With the second method, our client app will ask the web service to add a new record (a new album) to the right table on our example database.

How can we process the request associated data inside the HandleURL event? Here is where we will find very useful another of the Request object properties. The Body property includes the sent data as part of the request that are not already present in the headers. Generally speaking, it includes additional data via the PUT and POST verbs.

Now we can put the following code into our HandleURL Event Handler:

Select Case Request.Path // What is the method received as part of the request? (URL)
Case "GetAll"
  Var output As JSONItem = GetAllAlbums // Assign the processed data to the output variable, if the received method is 'GetAllAlbums'
  
  Response.Header("charset") = "utf-8"
  Response.MIMEType = "application/json"
  Response.Status = 200
  response.write( output.ToString ) // And send it back to the client that made the request, converting the JSON to a String in first place
  
Case "AddAlbum"
  Var data As String = Request.Body.DefineEncoding(encodings.UTF8) // We have to apply the right encoding to the received data
  Var Input As JSONItem = New JSONItem( data ) // Creating a new JSON object from it
  addNewAlbum( Input.Value("newAlbum") ) // In this case, the request is to add a new Album to the database; passing thus the received data as part of the input
End Select

Return True

The main point here is that we assign the received data to the data variable (if any), and define a known encoding to them so we won’t get into trouble while processing them afterwards. Of course, our example always expects to receive the additional data in JSON format, so this is why we create a new JSON instance from this data.

We use the Select…Case command to decide what method has to execute the web service, and that is based on the component stored in the Path property as you recall. So, if the request uses the GetAll method in the URL, we will call the real method GetAllAlbums in our Xojo code. After processing the information it will return a new JSONItem as the response we will send to the client.

How can we send the response to the request? Really simple: calling the Write method on the Response object, passing as parameter the text we want to send back. In our example, this is the JSONItem referenced by the Output variable. We also use the Response object to set the character encoding to UTF-8 and the MIME type to “Application/json”, in addition of setting the status value to 200 (that is, the request has been successfully handled).

If we receive a request with the AddAlbum method of our API, then we call the real addNewAlbum method in our Xojo code, passing as parameter the JSONItem object in charge of store the received data from the request (this is the one referenced by the input variable). In fact, the record structure is stored inside the newAlbum root node of the JSONItem.

When it comes to the Database

While HandleURL is in charge of processing the received request, we will use a couple of methods in our example app that will act as a link between the API and the database in the backend, both for retrieving and storing the requested information. (In a real world app it is very advisable to introduce checks and data sanitization before dealing with the database!)

Choose the App object again and use the Insert > Method option in order to add the GetAllAlbums method, using the following method signature for that:

• • Method Name: getAllAlbums
  • Return Type: JSONItem
  • Scope: Private

This is the code in charge of generating the JSONitem that we will write as part of the request response, including the node for every expected database record from the Album table in our example database:

Var rc As RowSet = database.SelectSQL("Select * from album order by title asc") // Get the Recordset as result of the SQL selection: all the records
Var item As New JSONItem

If rc.RowCount > 0 Then // We have records on the RecordSet
  
  While Not rc.AfterLastRow // so lets iterate them!
    Var d As New Dictionary // creating a new dictionary for each record, and that we will convert in a node
    d.Value("artistid") = rc.Column("artistid").StringValue // assingning the record ID to the name 'ArtistId' of the JSONItem
    d.Value("title") = rc.Column("title").StringValue // and the Title value to the 'Title' field of the JSONItem
    item.Value(rc.Column("albumid").StringValue) = d // You know you can assign a Dictionary as the value for a JSONItem node. Very useful!
    
    rc.MoveToNextRow
  Wend
  
  rc.Close
  
End If

var output As New JSONItem

output.Value("AllAlbums") = item // Then let's hang all these records form a main Node

Return output // And return it to the caller

Next, create a new method named addNewAlbum. This is the one our web service will use to add a new record to the database, using for that the received data as part of the request. Use the following signature for the method definition:

• • • Method Name: addNewAlbum
    • Paramters: item as JSONItem
    • Scope: Private

And put the following code in the associated Code Editor:

Var title As String = item.Value("Title") // get the data associated to the "Title" field
Var artistid As String = item.Value("ArtistId") // and the 'ArtistID'

database.ExecuteSQL("insert into album(title,artistid) values(?, ?)", title, artistid ) // and insert that data as a new record into the database table

As you can see, the code is very simple: it gets the values for the received keys in the JSONitem nodes and uses them as part of the SQL sentence in order to add a new record to the database.

A Web service… ready to serve!

As you have seen, the code and app structure are really minimal! Of course, this is just a simple example but it gives you a good idea of the kind of possibilities web services offer and how fast you can put it together using Xojo and OOP concepts you already know! Of course, you can run your web app (and services) right from the IDE (just make sure to select 8081 as the Debug Port)… what is probably the recommended way to follow this simple example. For other more complex web apps, remember that you can use the one click solution Xojo Cloud and of course any compatible Linux, Windows or Mac server.

Javier Rodri­guez has been the Xojo Spanish Evangelist since 2008, he’s also a Developer, Consultant and Trainer who has be using Xojo since 1998. He manages AprendeXojo.com and is the developer behind the GuancheMOS plug-in for Xojo Developers, Markdown Parser for Xojo, HTMLColorizer for Xojo and the Snippery app, among others

*Read this post in Spanish

The SQLite database has just a single table called Quote with this structure:

CREATE TABLE Quote (
ID INTEGER NOT NULL,
QuoteText TEXT,
QuoteSource TEXT, 
PRIMARY KEY (ID)
);

To randomly fetch a single quote from the table, this SQL is used:

SELECT QuoteText, QuoteSource FROM Quote ORDER BY RANDOM() LIMIT 1;

As companion apps, I’ve also included simple desktop and iOS apps that call the web service to display a quote.

The raw JSON that is returned looks like this:

{"QuoteText":"Simple things should be simple. Complex things should be possible.","QuoteSource":"Alan Kay"}

I’ve published a version of this on Xojo Cloud. Access the app.

Access the web service here.

You can download the projects or check it all out on GitLab.

Add your #JustCode project to the week 9 forum conversation.

Download and check out earlier projects:

• Week 8: JumpStart App Launcher
• Week 7: Pitch Tracker
• Week 6: Bubble Popper
• Week 5: Math Quiz
• Week 4: Mini-Golf ScoreKeeper
• Week 3: Dogs Up!
• Week 2: Password Generator
• Week 1: Color Picker

Slack has an API called “slash commands” that lets a user type a slash (/) followed by a command name in order to perform a special action. For example, Slack has many built-in slash commands, one example is /help. Here’s how you can easily add your own slash commands using a Xojo web app and the HandleSpecialURL (or HandleURL) method.

Your slash command makes an HTTP request to your Xojo web service app. The web services does its thing and then returns the result back to Slack to display.

A Xojo Web Service

For demonstration, I’m going to show you how to create a Slackbot that returns a “cat fact”. The slash command will be /catfact. When you use the /catfact command, Slack calls a Xojo web service which then makes a call to the Cat Fact API, parses the resulting JSON and returns an interesting cat fact back to Slack to display in your channel.

As I’ve covered in a couple Web Services webinars last year, it is pretty easy to make a web service using Xojo. For this example, create a new web project and name it CatFact.

First you will create a simple method that will fetch a Cat Fact. Create a method on the App object, GetCatFact As String, with this code:

// New request came in, so create a new HTTPSocket
Dim catSocket As New HTTPSocket

// Get a cat fact and wait for it to be returned
Dim factData As String = catSocket.Get("http://catfacts-api.appspot.com/api/facts?number=1", 30)

// Once the cat fact is returned, parse the JSON and send it to the original requester.
Dim jsonText As Text = DefineEncoding(factData, Encodings.UTF8).ToText
Dim jsonDict As Xojo.Core.Dictionary = Xojo.Data.ParseJSON(jsonText)
Dim facts() As Auto = jsonDict.Value("facts")

// Extract the fact text from the JSON
Dim fact As Text
If facts.Ubound >= 0 Then
  fact = facts(0)
End If

Return fact

In this Xojo project you’ll now create a simple web page UI to test that calling the Cat Fact API works. On the default page (WebPage1), add a Button and a TextField. In the Button’s Action event handler, add this code:

CatFactArea.Text = App.GetCatFact

Run the web app and on click the button. You should see a cat fact appear in the Text Area. The fact I got was:

The cat has 500 skeletal muscles (humans have 650).

Now you can add the code to process the web service request. Add the HandleSpecialURL event to the App object and use this code:

If Request.Path = "CatFact" Then
  Request.Print(GetCatFact)
  Return True
End If

You can test this by running the web project and then in a new tab entering the API URL, which displays a cat fact in the browser:

http://127.0.0.1:8080/api/CatFact

Hook Up Web Service to Slack

Now that you know the web service works, the next step is to hook it up to Slack. But before you can do that, you have to host the web app somewhere on the Internet; Slack can’t see your local web app! For this example, I’ve published the Cat Fact web service to Xojo Cloud because it’s fast and easy. This is the URL to the Cat Fact web service on Xojo Cloud:

http://demos.xojo.com/CatFacts/index.cgi/api/CatFact

Now you need to go to your Slack team settings to add a slash command. On that screen you’ll want to set the name of the Command to “/catfact” and the URL to “http://demos.xojo.com/CatFacts/index.cgi/api/CatFact” (the URL from above). Also change the Customize Name field to “CatFact”. You can ignore all the other fields and click the Save Integration button at the bottom.

That’s it. The slash command is now active. Head on over to your Slack team and type /catfact into a channel. You’ll get back a fact from “CatFact”.

And it took less than 20 lines of code! You can now use this technique to integrate your own web services into Slack.

By default, only you will see the cat fact returned by the Slashbot; it is not broadcast to the entire channel. You can change this by returning specifically formatted JSON rather than just a text string (as described on the Slack Commands API page).

If you come up with a great slash command and want to make it available to the world, you can attach it to a Slack app and publish it to the App Directory. The steps for this are also in the Slash Commands API page.

I did a little Google searching and found this one which seems to work well: https://github.com/sqlparser/sql-pretty-printer/wiki/SQL-FaaS-API-manual

To use it with Xojo, create a subclass of Xojo.Net.HttpSocket and drag it onto a window

This code in a button takes unformatted SQL from a TextArea and sends it to the web service, asking that it be formatted for Oracle (rqst_db_vendor=1):

 Dim sql As Text = SQLArea.Text.ToText
 Dim postText As Text = "rqst_input_sql=" + _
  EncodeURLComponent(sql).ToText + _
  "&rqst_db_vendor=1"

 Dim postData As Xojo.Core.MemoryBlock
 postData = Xojo.Core.TextEncoding.UTF8.ConvertTextToData(postText)

 SQLFormatter1.SetRequestContent(postData, _
  "application/x-www-form-urlencoded")
 SQLFormatter1.Send("POST", _
  "http://www.gudusoft.com/format.php")

This code in the PageReceived event handler of your HttpSocket subclass parses the resulting JSON and displays the formatted SQL:

Dim jsonText As Text
jsontText = Xojo.Core.TextEncoding.UTF8.ConvertDataToText(Content)
Dim json As Xojo.Core.Dictionary = Xojo.Data.ParseJSON(jsonText)
FormattedSQLArea.Text = json.Value("rspn_formatted_sql")

Download Sample Project

Looking for something to try next? Watch the video below and learn how to use HTTPSocket in the Xojo Framework.