Hosting a Web Service

import com.blobcity.db.sp.RestWebService;
import com.blobcity.db.sp.annotations.Rest;
import org.json.JSONObject;

@Rest(path = "/v1/sample-get")
public class GetWebServices implements RestWebService {
  
  public JSONObject get(JSONObject requestParams) { 
    return new JSONObject({\"ack\": \"1\"}");
  }
  
  public JSONObject post(JSONObject jsonBody, JSONObject requestParams) {
    return new JSONObject("{\"ack\": \"1\"}");
  }
}

The above class defines a simple web-service that returns {“ack”: “1”} as response for all calls. Both GET and POST requests are supported by the web service.

Each web service class is required to implement the RestWebService interface, which provide method signatures for implementing both GET and POST protocol web services.

Currently BlobCity web services may only offer the GET and POST protocols. Each web service class must implement both the GET and POST signature, but based on the desired usage, you may choose to support only one of the two protocols.

@Rest(path = “/v1/sample-get")

The annotation tells BlobCity that this class represents a web-service. The path param specifies the url for accessing the web service.

Once the stored procedure is loaded into the database, the web service would be hosted at following URL.

https://{data-centre}.blobcity.com/ws/{ds}/v1/sample-get

http://<ip>:<port>/ws/{ds}/v1/sample-get

The web service URL needs to have exactly two parts. It typically follows the convention of version number followed by the actual URL, but you could have any two items in the parts.

Valid:/v1/sample-get

Valid: /module/sample-get

Invalid: /v1/sample-get/read

Invalid: /sample-get

The method signature for the GET protocol includes a single parameter. The single parameter contains a JSON object representing all the URL / path parameters passed to the web service at the time of the GET call.

public JSONObject get(JSONObject requestParams)

http://localhost:10111/ws/my_ds/v1/get

http://localhost:10111/ws/my_ds/v1/get?name=Tom

http://localhost:10111/ws/my_ds/v1/get?name=Tom&age=45

{}

{
	"name": "Tom"
}

{
	"name": "Tom",
  "age": "45"
}

The POST request works in similar manner to the GET request. However the POST method as shown below takes two parameter. A POST request may have a request body as well as parameters.

public JSONObject post(JSONObject jsonBody, JSONObject requestParams)

The first parameter jsonBody takes in JSON body that is passed in the POST request. Only application/json types of requests are supported, and thus the jsonBody is always of JSON type. The second object represents key value pair parameters passed in the request.

Any implementation can be done inside the get and post methods. One can process the request by performing database operations, or may also call other web services.

The response of the web service must at all times be a JSONObject for both GET and POST requests. This response will be returned by the web service to the requester who invoked the web service.