HTTP Deep-Dive with Ballerina: Services

Anjana Fernando
Jan 28 · 6 min read
Image for post
Image for post

In this article, we are going to cover the HTTP services support in the Ballerina programming language (Swan Lake release). We will be looking at the basics of creating an HTTP service, and then see how the Ballerina language provides a convenient abstraction for defining complex operations as well.

Anatomy of an HTTP Service

A Ballerina service’s structure and its semantics are defined by the type of the service, i.e. the type of listener attached. Let’s take a look at how a basic HTTP service is structured in Ballerina.

Image for post
Image for post
Ballerina HTTP Service Structure

The full source code for the above hello service is shown below.

The execution of the service and its invocation is shown below.

Hierarchical Resources

Hierarchical resources in HTTP services are defined by providing the hierarchical path of the resource as the resource name. The path segments are separated using “/”. The following example shows how the path “/base/foo/bar” is represented in an HTTP service resource.

Resource path segments can be defined with parameters as well, in a similar way we define function parameters. This is done with the syntax [<type> <name>] in the path segment. The parameter type must be one of the types: int, string, float, boolean, decimal. Using this functionality, path parameters for the HTTP resource can be defined. Example usage of this is shown below.

There can be multiple resource path segment parameters, and they can be mixed and located anywhere with general path segments.

A resource path rest parameter can be used in order to represent zero or more path segments. An example of this is shown below.

This functionality can also be generally used in a situation where we want to dispatch all requests coming to a certain base path and its subpaths. This can be accomplished by having a [string… paths] resource path rest parameter. An example of this scenario is shown below.

Query Parameters

In a resource function, the query parameters are represented using the resource function parameters. The parameter type must be one of the types: int, string, float, boolean, decimal. The name of the parameter represents the query parameter name. An example of this functionality is shown below.

Payload Data Binding

The HTTP service resource payloads can be directly data bound to the resource function parameters. In order to distinguish between query parameters and resource payload parameters, the parameters which represent the resource payload are annotated with @http:Payload. The supported parameter types are string, json, xml, byte[], record types, and record array types.

Extended Request/Response Access

The service resources have the functionality of manually handling request and response data without binding them to resource parameters or the return value. This is done by optionally taking in http:Caller and http:Request typed parameters, which represent the calling remote client and the current request information respectively.

The http:Caller contains functionality to interact with the remote client, such as responding back to the client using the respond remote method. The http:Request object contains operations to look up information regarding the current incoming HTTP request, such as the request payload, query/matrix parameters, cookies, and headers.

The following example demonstrates this functionality in action.

Using this approach, we can also execute additional logic even after the response is sent back to the client. For example, in the case of a network issue in responding back to the client, we can do custom operations for failure-recovery, or do extended logging operations.

The respond remote method also takes in an http:Response object if we need more finer control in the response, such as setting the status code or override the default content type. The below code snippet shows how we can send an HTTP 202 (Accepted) status code from our response.

Multipart Message Handling

As similarly used in the HTTP client API, multipart messages can be created in service resources by using the Multipurpose Internet Mail Extensions (MIME) standard. Using the http:Response object, we can provide MIME entity values to create single or multi-part HTTP messages.

A MIME entity in Ballerina is represented using the mime:Entity object. The following code shows how to set a text payload in the response using a mime Entity.

The code above explicitly creates the MIME entity and sets it in the HTTP response. The same operation happens if we use the setTextPayload method in the http:Response object. These functions are effectively helper functions to set the MIME entities in the HTTP response for often-used content types.

The mime:Entity object contains functions for setting the body with other data types, such as binary, XML, and JSON, as well.

A multipart message can be created by setting the body parts in the mime:Entity object using the setBodyParts method. This method takes in an array of mime:Entity objects, and also optionally the content type of the enclosing entity, where the default is set to multipart/form-data. If required, we can override this with other multipart values such as multipart/mixed, multipart/alternative, and multipart/related.

The following example shows how a multipart/mixed message is created using plain text content and an image file as an attachment.

Here, the setContentDisposition method in the mime:Entity object is used to set the content disposition of the entity. This provides information on how the recipient should handle the data. For example, if it should be displayed inline, treated as form data, or downloaded as an attachment.

Secure Communication

The HTTP listener can be configured to enable transport security in order to restrict to HTTPS clients for communication. This is done by providing an optional ListenerConfiguration instance when creating the http:Listener client and providing the secure socket configurations. The following example shows how an HTTPS service is configured.


In this article, we took a look at the HTTP services functionality available in the Ballerina programming language. It provides an easy-to-use abstraction in mapping the HTTP functionalities to services and resources. In this manner, the developer can mainly concentrate on the business logic, rather than spending time on boilerplate code for transport-specific functionality. For more in-depth information on the HTTP APIs, check out the Ballerina API documentation for the HTTP module.

Also, quick examples of Ballerina features can be found in Ballerina by Example.


The Ballerina Tech Blog

Anjana Fernando

Written by

Author of ‘Beginning Ballerina Programming’ | Software Developer | Evangelist | 🇱🇰 🇺🇸 | Director — Developer Relations @wso2 — @lafernando


The Ballerina Tech Blog

Anjana Fernando

Written by

Author of ‘Beginning Ballerina Programming’ | Software Developer | Evangelist | 🇱🇰 🇺🇸 | Director — Developer Relations @wso2 — @lafernando


The Ballerina Tech Blog

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store