This topic follows the material in “Architectural styles
in Web services” and provides additional details on EGL support for
REST.
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.