Laying the foundation for RESTful web services

motif

Ever now and then you find a new piece of software or feature, which ends up changing the way you work, saving you time and just overall making things easier for you and your organization. We think that the RESTx project with its new 0.9.2 release gains such a feature. We call it “specialized components”. What is that, why is it useful and how will it make things easier for you? In a moment I will use an example for illustration, but let me first provide a little background on RESTx. If you are already familiar with RESTx, you can skip over the next chapter.

RESTx: A quick introduction

RESTx – we believe – is the fastest way to create web services. RESTx is a fully , small, stand-alone server. A RESTx server houses components – code that implements some functionality for data access, integration or processing, written in either or Python.

Because RESTx is RESTful you can simply visit the server’s URI with a browser and find the components you are interested in just by following links. Then you send the configuration parameters for the component to the server by POSTing them to the component’s URI. A small form is provided for your convenience, but you can also do this programmatically.

For example, for a database access component, you may send a DB connection string and query. The server returns to you a new URI, the “resource URI”. This URI can now be passed around, shared and clicked on. If accessed, the RESTx server applies the parameters to the code, executes it and returns the results. Users of the URI do not have to know about any of the required parameters or which code is executed behind the scenes.

This works great and is very useful; Your IT staff can provide code to access databases, custom or legacy APIs, cloud services, implement data process or integration logic, etc., while your knowledge workers can then rapidly create the RESTful services (useful URIs, as far as they are concerned) by providing parameters to those components. As a result, your IT staff can focus on providing the code, while your knowledge workers can quickly create reusable, RESTful web services out of them, which they need right now and which make sense to them in their context: /resource/Top10Customers makes much more sense and is safer than a URI full of query parameters.

The missing piece: Specialized components

Now with specialized components, we have added an important piece to the puzzle: It is possible for developers, IT staff or particularly knowledgeable workers to provide just some of the parameters, thereby creating a template from which further can be created. The canonical example here again is the DB access resource:

spec_comp_1

This is how the DB access component presents itself. We see some of the parameters that it requires. Clicking on “Create resource” brings up a small form in which the necessary parameters for this component are entered.

spec_comp_2

Here we see that only a partial set of parameters for this component was provided, including the DB connection string and the table name, while the query string was omitted. We also see that “Make this a specialized component” has been checked. The created ‘specialized component resource’ can be given a nice name and description, for example“EmployeeDB”. To create a complete and therefore usable resource from this, a user now only needs to provide the query string, since the DB connection string was already specified. In fact, whatever parameter was specified when the specialized component resource was created is not settable anymore:

spec_comp_3

We can see this after the specialized component resource was created. Some parameters have been set for us already and  the “is_settable” flag for those parameters has been set to “no”. When we now click on the “Create resource” link, we get a much simpler form to fill out, with only those parameters remaining, which were not specified during creation of the specialized component resource:

spec_comp_4

Here we create a new resource, which only contains data for employees that are ‘younger’. We see that the DB access string, table name and other more ‘technical’ details did not have to be provided.

Once this resource is created, we get a new URI called “/resource/YoungerEmployees”, which can be used directly without any further parameters:

spec_comp_5

Conclusion

Specialized components make re-use of component code easy: In order to hide parameters from your users or to set values for them, you don’t need to hard-code anything in the component code itself or rely on external configuration files. Instead, you can easily provide the settings you need while creating a specialized component. It then becomes very easy to create more resources based on this specialized component resource, merely by filling out the remaining parameters.

This works particularly well if you have a lot of different, but similar data sources, such as different database instances. You can quickly create a specialized component resource for each DB and use those as the basis for the rapid creation of specific RESTful resources in your organization.Ever now and then you find a new piece of software or feature, which ends up changing the way you work, saving you time and just overall making things easier for you and your organization. We think that the RESTx project with its new 0.9.2 release gains such a feature. We call it “specialized components”. What is that, why is it useful and how will it make things easier for you? In a moment I will use an example for illustration, but let me first provide a little background on RESTx. If you are already familiar with RESTx, you can skip over the next chapter.

RESTx: A quick introduction

RESTx – we believe – is the fastest way to create RESTful web services. RESTx is a fully RESTful, small, stand-alone server. A RESTx server houses components – code that implements some functionality for data access, integration or processing, written in either Java or Python.

Because RESTx is RESTful you can simply visit the server’s URI with a browser and find the components you are interested in just by following links. Then you send the configuration parameters for the component to the server by POSTing them to the component’s URI. A small form is provided for your convenience, but you can also do this programmatically.

For example, for a database access component, you may send a DB connection string and query. The server returns to you a new URI, the “resource URI”. This URI can now be passed around, shared and clicked on. If accessed, the RESTx server applies the parameters to the code, executes it and returns the results. Users of the URI do not have to know about any of the required parameters or which code is executed behind the scenes.

This works great and is very useful; Your IT staff can provide code to access databases, custom or legacy APIs, cloud services, implement data process or integration logic, etc., while your knowledge workers can then rapidly create the RESTful services (useful URIs, as far as they are concerned) by providing parameters to those components. As a result, your IT staff can focus on providing the code, while your knowledge workers can quickly create reusable, RESTful web services out of them, which they need right now and which make sense to them in their context: /resource/Top10Customers makes much more sense and is safer than a URI full of query parameters.

The missing piece: Specialized components

Now with specialized components, we have added an important piece to the puzzle: It is possible for developers, IT staff or particularly knowledgeable workers to provide just some of the parameters, thereby creating a template from which further resources can be created. The canonical example here again is the DB access resource:

spec_comp_1

This is how the DB access component presents itself. We see some of the parameters that it requires. Clicking on “Create resource” brings up a small form in which the necessary parameters for this component are entered.

spec_comp_2

Here we see that only a partial set of parameters for this component was provided, including the DB connection string and the table name, while the query string was omitted. We also see that “Make this a specialized component” has been checked. The created ‘specialized component resource’ can be given a nice name and description, for example“EmployeeDB”. To create a complete and therefore usable resource from this, a user now only needs to provide the query string, since the DB connection string was already specified. In fact, whatever parameter was specified when the specialized component resource was created is not settable anymore:

spec_comp_3

We can see this after the specialized component resource was created. Some parameters have been set for us already and  the “is_settable” flag for those parameters has been set to “no”. When we now click on the “Create resource” link, we get a much simpler form to fill out, with only those parameters remaining, which were not specified during creation of the specialized component resource:

spec_comp_4

Here we create a new resource, which only contains data for employees that are ‘younger’. We see that the DB access string, table name and other more ‘technical’ details did not have to be provided.

Once this resource is created, we get a new URI called “/resource/YoungerEmployees”, which can be used directly without any further parameters:

spec_comp_5

Conclusion

Specialized components make re-use of component code easy: In order to hide parameters from your users or to set values for them, you don’t need to hard-code anything in the component code itself or rely on external configuration files. Instead, you can easily provide the settings you need while creating a specialized component. It then becomes very easy to create more resources based on this specialized component resource, merely by filling out the remaining parameters.

This works particularly well if you have a lot of different, but similar data sources, such as different database instances. You can quickly create a specialized component resource for each DB and use those as the basis for the rapid creation of specific RESTful resources in your organization.


We'd love to hear your opinion on this post


2 Responses to “Laying the foundation for RESTful web services”

  1. Hi, could anyone please tell me how the connection string itself should look like? Because I am geting an internal error all the time. I am trying to connect to mysql database, I’ve put JDBC driver into RESTx/lib directory, I use such string : “jdbc:mysql://IP_of_machine_storing_DB:3306/nameOfDatabase?user=user&password=password”

  2. Hello Pawel,

    The database component that was bundled in the 0.9.2 version was for demonstration purposes only. But if you check out the latest sources from the git repository ( http://github.com/mulesoft/RESTx ) then you will get a much improved database access component. That one knows how to handle JDBC (you specify the driver class as one of the parameters during resource creation time).

    The database connection string is then going to be exactly like what you have specified.

    If you have any further questions, please contact me directly (I sent an email to the ‘info’ address at your work) or start a thread on our forums ( http://forums.mulesoft.org/forum.jspa?forumID=147 ), which are a great place for this sort of thing.