RESTful Web services

With Genero Business Development Language, you can write a RESTful Web Services client or server application.

The Calculator tutorial

There are several ways to implement REpresentational State Transfer (REST) Web services. This documentation uses a tutorial based on a calculator Web services application, using the HTTP interface with URIs and verbs.

This tutorial is provided from both the client and the server perspective. In Writing a Web services client application, you learn how to create a client application that accesses the Add function in a calculator Genero Web services server application, with the option to perform the data exchange in either JSON or XML. In Writing a Web Services server application, you learn how to implement the Web service on the server side.

REST Client-Server Separation

In REST architecture there is a client-server separation and each works independent of the other. Clients or user interfaces do not know, for instance, about data storage on the server side, and servers are not concerned with the user interface or the user state. Each can be developed independently.

To work, there must be an uniform interface which links the client and server. HTTP is the uniform interface REST uses for the communication between the client and the server. In terms of the design of a REST Web service client you use:

HTTP verbs (GET, PUT, POST, DELETE) to indicate the action to be performed on the Web service resource.
URIs (with resource name) to identify the server function or resource needed.
The following is an example of a request to calculator "add" resource on a Web service listening on port 8090 on localhost.
```
GET http://localhost:8090/add?a=1&b=2
```
HTTP request headers are needed (Accept and Content-type), to specify how to receive and deliver content, JSON or XML).

REST Web Service Resources

The RESTful Web services server provides access to resources that a RESTful Web services client can both access and modify, if allowed to do so. Web service resources are manipulated through representations. Representations are the state of the resource transferred between the client and the server. Typically, these representations are sent and received in JSON or XML format. If the client representation is to get some records from a database, the server does not send its database, instead it sends some JSON or XML that represents these records.

HTTP Request/Response Messages

Each HTTP request–response message between the client and the server must be self-descriptive and include enough information to process the message.

Note: To see incoming and outgoing messages (URI, HTTP headers, and HTTP bodies), set the FGLWSDEBUG environment variable before starting the GWS application. For more information on setting the debug mode, see Debugging.

The Web services client application request delivers state via body contents, query parameters, request headers, and the requested URI (the resource name). If you were to view the request in the standard output, you would see an interaction similar to that shown here. Comment lines (#) have been added to highlight the exchange.

# Connecting to Web server
Host :localhost\nPort :8090\nVia proxy :no\nIPv :4

# Send request to the add resource with query parameters (a & b), values (1 & 2), and HTTP version 
GET /add?a=1&b=2 HTTP/1.1

# send header information
Accept: application/json
Content-Type: application/json
User-Agent: GWS Agent (Build 1449830511)
Host: localhost:8090
Connection: close
Date: Tue, 29 Mar 2016 08:28:02 GMT
Content-Length: ???
Content-Encoding: ???

The Web services server response delivers state to the client via body content, response codes, and response headers. An example of the standard output of the response from the Calculator Web service is shown.

# Processing request... GET http://localhost:8090/add?

HTTP/1.1 200 OK

# Send HTTP response headers 
Content-Type: application/json
Server: GWS Server (Build 1449830511)
Connection: close
Date: Tue, 29 Mar 2016 08:28:02 GMT
Content-Length: ???
Content-Encoding: ???

# Send HTTP body with response codes (status; code and description) and result (r) in JSON format
{"status":{"code":0,"desc":"OK"},"r":3}

Web Services APIs

The Genero APIs for creating Web services can be found in the Library section of this manual. See The com package, The xml package, and The util package.