REST for the developer

This topic follows the material in “Architectural styles in Web services” and provides additional details on EGL support for REST.
Sections are as follows:

Resource, representation, URI, and action

From a developer point of view, REST involves the following main ideas:
  • A resource—for example, a database row with employee data—has (at a given time) a representation. A representation might be a set of program values that specify the employee number, title, and salary.
  • The resource—for example, a database row—also has a universal resource indicator (URI), which is a unique name such as "http://www.example.com/gateway/employee/0020". In this case, the employee number is 0020. In general, the URI gives a name to the resource. Also, the URI provides the main detail needed to access a REST service.
  • An action indicates what is to be done with the resource. The possible actions are few: the resource can be created, read, updated , or deleted.

The requester of a REST service identifies a resource, specifies an action, and (if the action involves resource creation or update) provides a representation of the resource.

Path variables and query strings

In HTTP, a URI may specify the resource of interest in the following ways:
  • The URI can include path variables, which are variables whose values identify the resource of interest in a direct way, without requiring that a service process the input to determine the resource. In the following example, the employee number 0020 is the value of a path variable:
    http://www.example.com/gateway/employee/0020
    Path variables are appropriate in most cases. You might use multiple path-variable values, with one separated from the next by a forward slash. That use of multiple values suggests a hierarchical relationship. For example, the path-variable values in the following URI identify a corporate division (Consumer) and, within that division, a corporate department (Sales):
    http://www.example.com/gateway/employee/Consumer/Sales
    When you write code to access third-party REST services in EGL, you create a URI template, which is an outline of the last part of a URI. Here is an example template, such that employeeNumber is a path variable:
    "/gateway/employee/{employeeNumber}"

    You identify a path variable in a URI template by embedding the variable name in curly braces.

  • In relation to a GET operation, the URI can be supplemented with a query string, which is a set of name-value pairs. In the following example, the question mark (?) precedes a query string, and each name-value pair is separated from the next by an ampersand (&):
    http://www.example.com/gateway/employee?division=Consumer&department=Sales
    A query variable is a placeholder for a value in the query string. When you create a URI template in EGL, you specify query variables by using the same syntax as for path variables. In the following example, divisionName and departmentName are query variables:
    "/gateway/employee?division={divisionName}&department={departmentName}"

    In comparison to the use of path variables, the use of query strings is considered less ideal—less RESTful. Use of query strings is most appropriate when a service uses the name-value pairs as input to the service logic. In that situation, the logic might use the input to determine what resource to access.

EGL support for a subset of third-party REST-RPC services

As noted in “Architectural styles in Web services,” a service that exchanges non-SOAP data by way of HTTP might be called a REST service even though the data exchange does not fully conform to the RESTful style. Here are some common variations:
  • Some REST services use a POST request for tasks other than creating a new resource. EGL lets you avoid sending a representation for a POST request.
  • Some REST services require that a DELETE request include a representation (the business data) rather than simply relying on the URI to identify the resource to delete. EGL supports access of REST services that require a representation for a DELETE request, but also supports access of REST services that do not have that requirement.

Feedback