REST for the developer

If you are a developer who is starting to work with REST services, you need to know the details of that style of service. For an introduction to REST, see “Architectural styles in web services.”

Resource, representation, URI, and action

From a developer point of view, REST involves the following main ideas:

At a given time, a resource, such as a database row of employee data, has a representation. A representation might be a set of program values that specify the employee number, title, and salary.
The resource 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 that is necessary 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 and specifies an action. If the action involves creating or updating a resource, the requester provides a representation of the resource.

Path variables and query strings

In HTTP, a URI can specify the resource of interest in the following ways:

The URI can include path variables, which are variables whose values identify the resource 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}"
```
Compared 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.