REST easy with kbmMW #1

In this case we will add a simple form both providing a GUI and a place for our kbmMW components.

In Delphi click File – New – VCL Forms application

Add one of each of the following kbmMW components to the form:

TkbmMWServer

TkbmMWTCPIPIndyServerTransport

Set the Server property of kbmMWTCPIPIndyServerTransport1 to kbmMWServer1.

Double click the Bindings property of kbmMWTCPIPIndyServerTransport1 to open its editor. Add a binding for 0.0.0.0 port 80, which is the default HTTP server port. You can choose any other binding you want, but make sure to tell your REST users which port to access.

In Delphi, Click File – New – Other – Components4Developers Wizards and select the kbmMW Service Wizard. Click OK.

Before continuing to select the type of kbmMW service we will add, we need to decide what type of REST server we want to create. It can be a pure REST server, which only serves data from your own code, or it can be a regular web server, which will also be able to serve data from files on disk, like html templates, images, CSS files etc.

For our purpose we just want to make a pure REST server, so we selectSmart service/kbmMW_1.0.

If you wanted it to be able to serve files from disk, and even proxy requests on to other FastCGI compatible servers (like PHP etc) you would have chosen HTTP Smart service.

Click the funny looking next button. Type in the default name your REST service should be known as. In this sample, I’ve called it MyREST.

Click next until you get to this page, then click the green checkmark button

Now an almost empty service has been generated for you.

On the surface it looks like a regular TDataModule, and as such can contain any component that you can put on a TDataModule. But right now we are more interested in its code. Press F12 to switch to code view.

Browse past the explanatory remarks at the top, until you get to the actual code.

type
[kbmMW_Service('name:MyREST, flags:[listed]')][kbmMW_Rest('path:/MyREST')]
// Access to the service can be limited using the [kbmMW_Auth..] attribute.
// [kbmMW_Auth('role:[SomeRole,SomeOtherRole], grant:true')]
TkbmMWCustomSmartService8 = class(TkbmMWCustomSmartService)
private
{ Private declarations }
protected
{ Protected declarations }
public
{ Public declarations }
// HelloWorld function callable from both a regular client,
// due to the optional [kbmMW_Method] attribute,
// and from a REST client due to the optional [kbmMW_Rest] attribute.
// The access path to the function from a REST client (like a browser)+
// is in this case relative to the services path.
// In this example: http://.../MyREST/helloworld
// Access to the function can be limited using the [kbmMW_Auth..] attribute.
// [kbmMW_Auth('role:[SomeRole,SomeOtherRole], grant:true')]
[kbmMW_Rest('method:get, path:helloworld')] [kbmMW_Method] function HelloWorld:string;
end;
implementation
uses kbmMWExceptions;
{$R *.dfm}
// Service definitions.
//---------------------
function TkbmMWCustomSmartService8.HelloWorld:string;begin Result:='Hello world';end;

The interesting bits are shown above in bold.

If you compile and run your application now, you have a REST only capable webserver which have one function… HelloWorld taking no arguments, and that returns a string.

Open up your favorite web browser and lets test the function by typing this in the address field:

Make sure that case is correct, since the HTTP standard describes that the URL part of the address must be case sensitive. If you would write http://localhost/MyREST/HelloWorld instead you would be told that the request is invalid.

This is all nice… but my REST client expect to receive a JSON object, not just simple text.

Ok.. I’ll show 3 ways to do that… the very manual way, the semi automated way and the fully automated way.

This allows you to create complex JSON documents pretty easily. The cool part is that since we use kbmMW’s object notation framework, we could have chosen to stream it as XML or YAML or BSON or MessagePack instead by simply instantiating the appropriate streamer.

The automated way simply means returning an object with the desired information. kbmMW will automatically convert the object to JSON (because we are using the REST streamformat).

To make sure that kbmMW knows about the object type, we register it via the kbmMWRegisterKnownClasses. If we didn’t, kbmMW would complain that it do not know about the object.

Do not worry about the TMyResult instance being leaked. kbmMW will automatically free it when it goes out of scope. If you specifically do not want the returned object to be freed by kbmMW, you can tell so by including freeResult:false in the kbmMW_Rest attribute for the HelloWorld method.

Also notice that the kbmMW_Rest attribute now includes anonymousResult:true.

This tells kbmMW that we want the resulting JSON to be anonymous. If we didn’t include that attribute setting, the result would have looked like this:

{"TMyResult":{"Result":"Hello world"}}

Which is not necessarily wrong, but different.

There are lots of control options of how the object should be streamed by setting various attributes on it. One can for example choose that the Result property should be returned under a different name etc.

kbmMW also understands returning TkbmMemTable instances, arrays and many other types of information, so it is really easy to REST’ify your kbmMW business functionality with almost no lines of additional code.

As a final comment, since the HelloWorld method is also tagged with the attribute [kbmMW_Method], it is also callable by native kbmMW clients.