Create a non-Genero client for a JSON Web service

In order to consume a BAM-generated JSON Web service, a developer must ust understand the format of the HTTP REST JSON operations (requests and responses).

Before you begin, get the WebService_serverclient.4gl file from the Web Service provider. Although written in Genero BDL, this file contains the information needed to create the JSON body for the requests and responses. Consider this file as the documentation of how the Web service works.

From this document and from the information and examples provided below, you should be able to construct the appropriate HTTP REST JSON operations. This means you need to be able to construct:
  • The URL of the REST resource.
  • The HTTP header, to include the HTTP method, additional REST resource, and a possible CRUD operation.
    • The HTTP method will be either GET, PUT, POST, or DELETE.
    • The resource provides additional URL details that specify which record is involved in the request
    • Some CRUD operations require you to provide the CRUDOperation in the header, specifically when you read, update or delete a collection.
  • The request body and response body. Data is exchanged in JSON format over HTTP. Examine the WebService_serverclient.4gl file to identify what is expected for both the request AND the response.
    • The request body provides the data that the Web service needs to do its work. In the WebService_serverclient.4gl file, this is managed using a record with the suffix _IN_type.
    • The response body provides the client application with the status of the operation (where 200 indicates success) along with any additional data sent back by the service. In the WebService_serverclient.4gl file, this is managed using a record with the suffix _OUT_type.

URL of the REST resource

The URL of the REST resource takes the following format:

http://<server>/<alias>/ws/r/<group>/REST/<resource>[(<IDs>)]

where:
  • <server> - Service server name or IP address.
  • <alias> - fastcgi / http dispatcher configuration
  • <group> - Web service server, for example, GAS group configuration or external configuration file name
  • <resource> - Web service entity
  • <IDs> (optional) - List of identifiers for records. IDs are enclosed by single quotes and separated by commas.

JSON Service example

Study these examples regarding the URLs and methods for a RESTful Web service. In this example, the JSON Web Service entity (with a Service Name of "Customers") involves three records (Accounts, Orders, and LineItems) defined with master-detail relationships.
Note: The Customers web service example used for these topics can be found under the Four Js Genero github repository. See http://github.com/FourjsGenero/ex_bam_json_web_service

Figure: Customers Web Service example with master-detail relationships


screenshot of master-detail relationships between records for a Customers Web Service entity
Table 1. This table is describing the REST JSON request and response
Functional description URL of the REST resource Scope HTTP Method CRUD operation Request Body Response Body
Returns a list of all customers

(i.e., accounts + orders + lineitems)

http://localhost:8090/ws/r/JSONServer/

REST/Customers

Collection POST READCollection Query By Example Error number + Collections of customers
Return the account "dupont" http://localhost:8090/ws/r/JSONServer/

REST/Customers/Accounts('dupont')

Item GET   Primary Key Error number + Account data for customer dupont
Return the order 1 http://localhost:8090/ws/r/JSONServer/

REST/Customers/Accounts/Orders(1)

Item GET   Primary Key Error number + Order data for order 1
Delete a list of accounts http://localhost:8090/ws/r/JSONServer/

REST/Customers/Accounts

Collection POST DELETECollection Array of Keys Error number
Delete the account "dupont" http://localhost:8090/ws/r/JSONServer/

REST/Customers/Accounts('dupont')

Item DELETE   Primary Key Error number
Update a list of accounts http://localhost:8090/ws/r/JSONServer/

REST/Customers/Accounts

Collection PUT UPDATECollection Array of Data Error number
Update the account "dupont" http://localhost:8090/ws/r/JSONServer/

REST/Customers/Accounts('dupont')

Item PUT   Data Error number
Create a document (createAll) http://localhost:8090/ws/r/JSONServer/

REST/Customers

Collection POST   Array of Data Error number + collection of keys
Create a list of accounts http://localhost:8090/ws/r/JSONServer/

REST/Customers/Accounts

Collection POST   Array of Data Error number + collection of keys

JSON resources

The implementation of a JSON Item of the Business Application diagram defines a data set. In a data set, each record defines one resource and provides methods to create, read, update, and delete data.

Table 2 shows the resources defined for the JSON item Customers of our example. This item provides three records, Accounts, Orders, and LineItems.

Table 2. Resources
Resource URI
Customers /Customers
Accounts /Customers/Accounts
Orders /Customers/Accounts/Orders
LineItems /Customers/Accounts/Orders/LineItems
Table 3 provides examples of the the HTTP header information necessary to complete CRUD operations on the resources in our example. In addition, the final three columns would map to the related function, the record used for the request body, and the record used for the response body.
Table 3. HTTP requests
HTTP header
  Description Related function Request record Response record
POST /Customers
  Creates a collection of documents. Customers_client_createAll() createAll_IN_type createAll_OUT_type
POST /Customers

CRUDOperation: READCollection

  Reads a collection of documents from a Query by Example (QBE). Customers_client_readAll() readAll_IN_type readAll_OUT_type
POST /Customers/Accounts
  Creates a collection of new accounts. Customers_client_Accounts_create() Accounts_create_IN_type Accounts_create_OUT_type
GET /Customers/Accounts('accountID')
  Reads the account specified by accountID. Customers_client_Accounts_readRow() Accounts_ws_br_uk_type Accounts_read_OUT_type
PUT /Customers/Accounts

CRUDOperation: UPDATECollection

  Updates a collection of accounts Customers_client_Accounts_update() Accounts_update_IN_type Accounts_update_OUT_type
PUT /Customers/Accounts('accountID')
  Updates the account specified by accountID. Customers_client_Accounts_updateRow() Accounts_ws_br_uk_type Accounts_update_OUT_type
POST /Customers/Accounts

CRUDOperation: DELETECollection

  Deletes a collection of accounts Customers_client_Accounts_delete() Accounts_delete_IN_type Accounts_delete_OUT_type
DELETE /Customers/Accounts('accountID')
  Deletes the account specified by accountID. Customers_client_Accounts_deleteRow() Accounts_ws_br_uk_type Accounts_delete_OUT_type
POST /Customers/Accounts/Orders
  Creates a collection of new orders. Customers_client__Orders_create() Orders_create_IN_type Orders_create_OUT_type
GET /Customers/Accounts/Orders('orderID')
  Reads the order specified by orderID. Customers_client__Orders_readRow() Orders_ws_br_uk_type Orders_read_OUT_type
PUT /Customers/Accounts/Orders

CRUDOperation: UPDATECollection

  Updates a collection of orders Customers_client__Orders_update() Orders_update_IN_type Orders_update_OUT_type
PUT /Customers/Accounts/Orders('orderID')
  Updates the order specified by orderID. Customers_client__Orders_updateRow() Orders_ws_br_uk_type Orders_update_OUT_type
POST /Customers/Accounts/Orders

CRUDOperation: DELETECollection

  Deletes a collection of orders Customers_client__Orders_delete() Orders_delete_IN_type Orders_delete_OUT_type
DELETE /Customers/Accounts/Orders/LineItems('lineItemID')
  Deletes the line item specified by lineItemID. Customers_client__Orders_deleteRow() Orders_ws_br_uk_type Orders_delete_OUT_type
POST /Customers/Accounts/Orders/LineItems
  Creates a collection of new line items. Customers_client__LineItems_create() LineItems_create_IN_type LineItems_create_OUT_type
GET /Customers/Accounts/Orders/LineItems('lineItemID')
  Reads the line item specified by lineItemID. Customers_client__LineItems_readRow() LineItems_ws_br_uk_type LineItems_read_OUT_type
PUT /Customers/Accounts/Orders/LineItems

CRUDOperation: UPDATECollection

Updates a collection of line items Customers_client__LineItems_update() LineItems_update_IN_type LineItems_update_OUT_type
PUT /Customers/Accounts/Orders/LineItems('lineItemID')
  Updates the line item specified by lineItemID. Customers_client__LineItems_updateRow() LineItems_ws_br_uk_type LineItems_update_OUT_type
POST /Customers/Accounts/Orders/LineItems

CRUDOperation: DELETECollection

Deletes a collection of line items Customers_client__LineItems_delete() Orders_delete_IN_type Orders_delete_OUT_type
DELETE /Customers/Accounts/Orders/LineItems(''lineItemID')
  Deletes the line item specified by lineItemID. Customers_client__LineItems_deleteRow() Orders_ws_br_uk_type Orders_delete_OUT_type