Designing REST methods

Previous Next

A client can only successfully call a REST service by calling a REST method. A REST method is one precise task that the service offers to its clients. Therefore, when you create a custom REST service, you must also create one or more REST methods. Declare each method on the Methods tab of your custom REST service by providing values for the method properties listed below.

You can have initial code generated on the basis of SQL statements. This involves automatically generating the method's Signature, Implementation, and Parameters (as appropriate). For an example, go to help topic " Example: a REST service for retrieving data ".

Method Name

Each method must have a Method Name that is unique within the REST service it belongs to. Each method corresponds to a precise task that the service offers to perform.

Relative URI Path

A REST method must have a Relative URI Path starting with a slash ('/'). It is customary to name the URI Path after the resource being queried or manipulated, for example, /ActiveBooking. Multiple methods within the same REST service may share the same Relative URI Path as long as they have different HTTP Verbs.

REST HTTP Verb

Because REST uses the underlying HTTP protocol, each REST method is associated with one of the (4) specific HTTP commands or verbs listed below. As the listing shows, each verb generally maps to one of the main verbs from SQL's Data Manipulation Language and is used for the same use cases as the corresponding SQL verb:

REST HTTP Verb

SQL Command

Use case

GET

SELECT

Query, retrieve data

POST

INSERT

Add new data

PUT

UPDATE

Change existing data

DELETE

DELETE

Drop existing data

Example

A REST service offers the possibility to add extra participants to an existing booking for a trip. A user wants to (re)set the number of participants of reservation with ID 154 to 4. The request URL is:

http://localhost:8090/myservice/myconnection/CURRENT_BOOKING;RES_ID=154;

The user or software issuing the request must be instructed to specify the HTTP method to PUT. This method requests specific input, which could look like this (if the Content Type is "text-xml"):

<CURRENT_BOOKING NUM_PART="4"/>

Or it could look like this, if the Content Type is "application/json":

{"NUM_PART" : "4"}

 

In this case, the most logical HTTP Verb to associate this functionality with is PUT.

Signature

A method's Signature is the header code that is actually called when a service client browses the method's Relative URI Path using its HTTP verb.

Implementation

A method's Implementation is the body code that is actually called when a service client browses the method's Relative URI Path using its HTTP verb.

Parameters

A method's Parameter(s) (as appropriate) specify the names and datatypes of information that is passed to the method and that the method passes back as a result.

Initial code

In USoft Service Definer, you can have REST methods generated on the basis of SQL statements. This involves automatically generating the method's Signature, Implementation, and Parameters (as appropriate). For an example, go to Example: a REST service for retrieving data.

Next steps

You are now ready to test and debug your custom REST service. Remember to re-publish the service each time you decide to make changes to the code.

See Also

Example: a REST service for retrieving data