Getting Started

After you have successfully build BlueDroplet you should have a couple of modules and the binding directory DROPLET where all necessary modules have been registered.

Exports

All BlueDroplet prototypes, template data structures and constants can be imported by including the file bluedroplet_h.rpgle.

/include 'bluedroplet/bluedroplet_h.rpgle'

Don't forget to set the INCDIR parameter to the correct IFS folder.

Modular Design

Of course everything can be munched into one source file but it is more maintainable if the code is split into multiple modules.

Main Module

The main module will configure and start the web server. It provides the program entry point. The REST endpoints will be registered in the main module.

dcl-proc main;
  dcl-s service pointer;

  service = droplet_service_create();

  droplet_service_enableLogging(service : *on);
  droplet_service_setLogLevel(service : DROPLET_LOG_LEVEL_DEBUG);

  droplet_service_addEndPoint(service : %paddr('sayHello') : '/say' : DROPLET_GET);

  droplet_service_start(service);

  droplet_service_finalize(service);
end-proc;

In this example the procedure sayHello is registered for the path /say for the HTTP method GET. This means that only HTTP GET request are routed to this procedure. And also the path must match. A HTTP GET request to http://ibm_i_server:8484/say will get routed to this endpoint. But a HTTP GET request to http://ibm_i_server:8484/world won't be routed to the procedure sayHello. Though http://ibm_i_server:8484/say/hello will get routed to sayHello as paths with a matching start are also valid for routing (though this is subject for change in the future where placeholders will be used in the registered path).

REST Endpoints

Each REST endpoint is coded as a procedure. Procedures should be grouped into a module by their domain.

The procedures for the endpoints must implement a specific procedure interface:

dcl-pi *N;
  service pointer const;
  connection pointer const;
  message pointer const;
  endpoint pointer const;
end-pi;

You don't need to know what lies behind these pointers. You can use them with the various procedures provided by the project.

Returning data is really simple and you can do that in just one line of code.

droplet_service_send(connection : DROPLET_OK : 'Hello World' : DROPLET_TEXT);

That's it!

Build

You can build this with a simple CRTBNDRPG like this:

CRTBNDRPG PGM(BDHELLO) DFTACTGRP(*NO) ACTGRP(*CALLER)            
STGMDL(*TERASPACE) BNDDIR(DROPLET) INCDIR('/usr/local/include')                                           

NOTE: It is important to use the storage model *TERASPACE as all modules in one program must have the same storage model and the web server (Mongoose) requires the storage model *TERASPACE.

Starting the Server

You can start the REST service just by calling the program you created in the Build section like

CALL BDHELLO

Ending the Server

You can end the server by ending the job. Though this is not a very nice way of doing it.

The server can also be ended in a controlled way by adding an environment variable entry like this before starting it:

ADDENVVAR ENVVAR(BLUEDROPLET_LIB) VALUE(MSCHMIDT)

The server will check for the environment variable and will create a data area in the configured library with the name DROPLET. Now you can end the server by changing the content of the data area to '0' (zero) or by just deleting the data area.

DLTDTAARA MSCHMIDT/DROPLET

Calling the REST Service

You can call the REST service with any tool you like. curl can be very handy when making REST calls.

Calling our service would look like this:

curl http://ibm_i_server:8484/say

And you will get a nice

Hello World

Wrap up

With just a few lines you can create your own real REST service where you are in full control on how the user calls your service and what your service returns.

Welcome to the REST of the world! =)

For the full example source code look here at Hello World.