CentraSite 10.7 | CentraSite User’s Guide | Asset Management | Managing Assets through CentraSite Business UI | REST Service Management | Adding REST Service from Scratch | Adding Resource to REST Service
 
Adding Resource to REST Service
Resources are the basic components of a REST Service.
After you have exposed the base URIs for accessing the REST Service, you must identify and first define the resources for it. By identifying the resources in the REST Service, you can make the REST Service more useful and easier to develop.
Each resource has its own unique URI. Defining URI patterns is important because URIs enable clients to directly access a resource.
For example, consider the case of our sample Phone Store Service. Assume this Service exposes a database that defines a list of phones and the features and specifications of each phone; wherein the list of phones is represented with the collection URI and the features of each phones is represented as an individual URI.
Collection resource URI: /phones
Unique resource URI: /phones/412456
Software AG recommends that you follow these simple tips and guidelines for structuring the resource path (URI):
*Short name URIs as much as possible - for example, prefer /phones/412456 than /phones/phone.php?phone_id=412456
*Straightforward and meaningful URIs to ease use of the resource - /phones/412456
*Consistent and predictable URIs patterns -/phones/412456/features
*Simple and hierarchical URIs to represent the relationships - for example,
*/phones
*/phones/412456
*/phones/412456/features
*Nouns, not verbs - for example, plural nouns to represent list of things - /phones; singular nouns to represent a particular thing - /phones/412456
*Hyphens, avoid spaces or underlines to improve and enhance aesthetic interaction with the resource - for example, prefer /phones/412456 than /phones/412456
*Lower case, avoid mixed case and upper case to improve readability - /phones/412456 than /Phones/412456
Here are some common examples for our sample resource /phones:
*/phones
*/phones/412456
*/phones/412456?fields=(make,features,bodytype)
*/phones/412456/make
*/phones/search?q=(make,eq,apple)
*/phones/?make=apple&features=3g&price.min=44101
In this task, you identify the resource of the REST Service and capture the resource URI for the REST Service. Indirectly, a URI address implies the relationship between each of the resources.
*To add a REST Resource
1. In CentraSite Business UI, access the Advanced Search panel in one of the following ways:
*Click the Browse link in the upper-left corner of the menu bar.
*Click the Search icon next to the Scope list. The default search scope is Assets.
This displays a list of assets in the Search Results page.
2. In the Additional Search Criteria list, select Asset Types.
3. To search for the assets of type, REST Service, click Choose.
This opens the Choose Asset Types dialog box.
4. In the Choose Asset Types dialog box, select the Assets option button, and perform the following:
a. Click the chevron next to Assets option button.
A list of defined asset types in CentraSite is displayed.
b. In the list of asset types, select REST Service.
c. Click OK.
A list of defined REST Service assets is displayed in the Search Results page.
5. Click the REST Service you want to add the REST Resource.
This opens the REST Service details page. Also, the Actions bar displays a set of actions that are available for working with the REST Service.
6. On the actions bar of the REST Service details page, click Edit.
7. Select the Resource and Methods profile.
8. Click the Add Resource link.
This opens the Add Resource dialog box.
9. In the Add Resource dialog box, provide the required information for each of the displayed data fields.
Field
Description
Resource Name
Name of the REST Resource.
Note:
This is the name that users will see when they view this REST Resource in the CentraSite User Interfaces. Therefore, specify a meaningful name for each REST Resource.
The name of a REST Resource must be NCName-conformant, meaning that:
*The name must begin with a letter or the underscore character (_).
*The remainder of the name can contain any combination of letters, digits, or the following characters: . - _ (that is, period, dash, or underscore). It can also contain combining characters and extender characters (for example, diacriticals).
*The name cannot contain any spaces.
For more information about the NCName type, see http://www.w3.org/TR/xmlschema-2/#NCName
Note:
If you are specifying multiple Resources for a particular REST Service, the name must be unique among all of the resources within that REST Service.
Resource Path
The Resource URI.
Make sure that you specify the URI with the simple tips and guidelines described above.
Important:
As a best practice, Software AG recommends that you adopt the following conventions when specifying a path parameter in the resource URI:
*Append a path parameter variable within curly {} brackets.
*Specify a path parameter variable such that it exactly matches the path parameter defined at the Resource level.
Description
(Optional). The description for the REST Resource.
Note:
This is the description information that users will see when they view this REST Resource in the CentraSite User Interfaces. Therefore, specify a meaningful description for each REST Resource.
Parameters - Add Parameter (link)
(Optional). Request Parameters for the REST Resource. You can select an existing global parameter defined on the Components page or enter a new parameter. The supported parameters types are:
*Path
*Query-String
*Header
*Form
Although CentraSite allows you to define parameters of the type, Form, at the Resource level, these parameters are not supported at run-time. Only parameters of the type - Path, Query-String, and Header, are supported at run-time.
Note:
You cannot add more than one parameter with the same name and the same type for a REST Resource.
a. Click the Add Parameter link.
This opens the Add Parameter dialog box.
b. In the Add Parameter dialog box, provide values for the REST Parameter.
c. Click OK.
The newly created parameter is added to the REST Resource.
To further update the new parameter, hover over the required parameter, and click the Edit icon. Repeat for each parameter for which you want to modify the details.
To specify multiple parameters, click the Add Parameter link, and provide values for the new parameters.
10. Click the chevron next to the REST Resource for which you want to display the details.
11. To further update the new REST Resource, hover over the required Resource, and click the Edit icon. Repeat for each Resource for which you want to modify the details.
12. To specify multiple REST Resources, click the Add Resource link, and provide values for the new REST Resource.
13. Click Save.