About RESTful Resources
What is a RESTful Resource?
A RESTful resource is the easiest way to make data available to your users and client applications alike, using well-defined interaction patterns and widely used protocols. At the same time, RESTx's RESTful resources effectively hide details about underlying implementation issues from your users and clients.
Whether it is business critical data for your knowledge workers, information for integration with business partners or building blocks for web-based mashups: Presenting data as a RESTful resource (and using HTTP as the protocol) greatly simplifies your data integration and publishing tasks and fits well into the prevailing network environment and infrastructure.
Oftentimes data is not present in a simple flat file, but actually needs to be produced on demand, when requested by a client application or user. For example, assume you have an SQL database with customer information. Your knowledge workers may be interested in the “top 10 customers of the current quarter”. To get this information a query needs to be executed, but of course you cannot distribute access credentials to your database or expect your users to write SQL queries.
Therefore, RESTx allows you to combine code (the component) with specific sets of parameters and to later re-use this combination in the form of a resource. Your clients and users only see the resulting data and are isolated from any specifics. This allows you to modify the way in which the data is produced at a later time, while clients continue to access the resource without having to be aware of any changes.
Every resource is uniquely identified by a resource URL. The URLs can be emailed around, used by client applications, accessed by web-browsers or any other HTTP capable client application. This makes them ideally suited as handles to disseminate fresh and current information in the most portable and compact way.
Creating and using a RESTful resource
A client (possibly an administrator) inquires about one of the available components on a RESTx server, in this case a database access component. The server returns names and descriptions of the various parameters that are accepted by the component. This ability of self-discovery allows for lose coupling between server and client: The client does not have to have built-in knowledge about the server. See figure 1 for details.
Figure 1: A client discovers details about an available component.
The client can now create a resource merely by sending an HTTP POST request, which provides a suggested name and values for the required parameters of the component. The server stores this combination and makes it available as a resource at a new URL. See figure 2 for illustration.
Figure 2: Creating a RESTful resource. All steps take place in the context of a single HTTP POST request.
Note that it is not the cached output data that is made available at the resource URL. Instead, whenever a client accesses this resource URL the RESTx server invokes an instance of the component, applies the stored parameters and returns the dynamically produced output as the data of the resource. See figure 3.
Figure 3: Using a RESTful resource. In this example an HTTP GET request is used. However, depending on the resource, PUT, POST or DELETE may also be supported.
The server automatically renders the data in a representation that was specified in the client's request. For example, a web browser may send the Accept:text/html header in the HTTP request. In that case, RESTx renders the data in browsable, human readable HTML. On the other hand, a client application may send Accept:application/json. In that case, data is returned as JSON, which is easily handled by automated clients. A number of different representations is supported.
In addition to exposing resources to clients, they are also easily usable by component code. For example, a component may receive the URL of another resource as a source of run-time input. Therefore, resources are reusable in a variety of different contexts. Furthermore, it is possible to build data pipelines out of chained resources.
What's next?
Our documentation page holds a lot of useful information. A few highlights you may be interested in: