Taking a tour of the RESTx server with your web browser

So you installed and started RESTx. Ready to see what the server has to offer? Nothing is easier than that: You just have to access the server with your web browser by going to http://localhost:8001.

Home page and navigation

The first thing you see once you hit the server is the 'home page'.

You can see some basic information about the server, such as a version and name. Most importantly, however, the server returns several links to you, which allow you to find more information. One of the key aspects of a RESTful system, such as RESTx, is that all possible data can be reached via links. The only starting URI you need to know is the root URI “/”. From there, everything else can be discovered.

What you see is a very common way for RESTx to present information to you: Sets of name/value pairs, commonly referred to as maps or dictionaries. For example, the name “doc” refers to a URI “/meta/doc”. The value itself may be a number, a string, a boolean value, another map or a list. This allows the construction of arbitrary complex, hierarchical sets of information.

To get a feel for navigating around the RESTx server, click on the “doc” link: You should see something similar to this:

For this page, RESTx merely returned a simple string to you, containing a small documentation about the server.

Note the navigation breadcrumbs at the top, telling you where you currently are on the server and giving you a quick navigation option. Use the breadcrumbs to navigate back to the server's home page by clicking on 'Home' or the 'back' button in your browser.

Exploring components

A component is a piece of code implementing a specific capability. RESTx provides a very straight forward API, allowing you to write your own components in multiple languages. Your RESTx server also comes bundled with a few basic components. To find out more about components, click here.

We can see all the available components at a glance by clicking on the “/code” link, which you can find on the server's home page. Your browser now displays the names of all components, along with their URI and a short description about each of them.

To dig deeper, let's click on the link for the 'TwitterComponent'.

Several important pieces of information are now displayed about this component. From top to bottom, you see the following fields:

desc: A short description of the component.

doc: A link to a documentation page for the component.

name: The name of the component. This is also used to identify the component in the component list and is part of the component's URI.

params: Information about each of the parameters that can be specified during resource creation time. These parameters are declared by the component code itself (“I need to know these things to be able to work!”) and make up the configuration of the component. When you create a resource for a component, you supply these configuration items. More than one configuration may exist for a component at any given time. As you would expect, a Twitter component needs an account name and password to be able to access the Twitter account. Therefore, these two data items are defined as parameters. You see the name of each parameter, a small description, the type, whether the parameter is mandatory or optional, and so on. Note that here we are only seeing the parameter definition, not actual parameter values. If this appears a bit abstract, don't worry. This soon becomes very clear when see an example of how to create a resource.

resource_creation_params: While “params” is specific to the component, this field instead defines a few parameters that need to be provided for all resources when they are created. Specifically, a suggested name for the new resource and a description; those are needed no matter which component we are dealing with. To continue with the Twitter example: If your Twitter account-name is 'xyz' then you could for example name the resource “TheXyzTwitterAccount” and specify as description “This resource gives you access to XYZ's Twitter account.”

services : This shows us what services (or 'sub-resources') are accessible for this resource, along with a  small description and which parameters they require, if any. An example is going to clarify that in a moment.

All of this is very interesting and tells you about the attributes, features and capabilities of a component. Now it's time to do something useful; time to create a resource for this component.

Creating resources

While on this page, take a look at the top, just between the navigation breadcrumbs and the start of the component description. You see a “[ Create resource ]” link. Click on it and you see a form with fields for all the necessary parameters to create a resource based on this component.

There you can fill in the name you would like to give the new resource, along with a small, personalized description. You also need to specify the Twitter account name and password. Once you have done all that, click 'Submit'.

The server has accepted your provided component configuration and stored it as a new resource. You see a page summarizing the outcome of the resource creation operation. Please follow the link labeled 'uri', which leads you to your newly created resource.

Using resources

After you clicked on the link to a resource, you see the resource overview page:

This is very compact and only contains information that is important to the user of the resource. Many of the details you provided when creating the resource are hidden from this view. That is deliberate, since creating a resource encapsulates certain configuration information that the user of the resource just does not need to know or be concerned about.

Note that the URI of the resource itself just gives you information about the resource. To start using it and to access data, follow the links to the services or sub-resources. For example, you can click on the link for the 'status' service to see the latest status update to that Twitter account.

Exploring components

To see a list of all available resources, go back to the server's home page and click the “/resource” link. This gives you a list of all available resources and for each of them a short description and link to the resource overview page.