SOA Governance and API Management : Working with REST-based APIs : Creating a RESTful API from Scratch : Adding Resource to REST API
Adding Resource to REST API
Resources are the basic components of a REST API.
Pre-requisites
After you have exposed the base URIs for accessing the API, you must identify and first define the resources for it. By identifying the resources in the API, you can make the API 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 API. Assume this API 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
We recommend 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 API and capture the resource URI for the API. Indirectly, a URI address implies the relationship between each of the resources.
To add a resource
1. Display the details page of the REST API (see Viewing the Details of a REST API for details).
2. In the actions bar for the API, click the Edit icon.
3. Select the Resource and Methods profile.
4. Click the Add Resource link.
5. In the Add Resource dialog box, enter the following information in the fields provided:
In this field...
Do the following...
Name
Mandatory. Enter a display name for the new resource.
This name 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: . - _ (such as, period, dash, or underscore). It can also contain combining characters and extender characters (for example, diacriticals).
*The name cannot contain any spaces.
*Furthermore, if the REST API name contains any non-conformant character, upon publishing the virtual copy of this REST API to any gateway, the non-conformant character is simply replaced with the underscore character (_) in Mediator. However, in CentraSite the REST API name defined by you is displayed.
For more information about the NCName type, see http://www.w3.org/TR/xmlschema-2/#NCName
Note:  
If you are specifying multiple resources for an API, the name must be unique among all of the resources in that particular API.
Resource Path
Mandatory. Enter the new resource URI. Structure the URI with the simple tips and guidelines described above.
Important:  
As a best practice, we recommend 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. Enter a description for the new resource.
Note:  
This is the description information that users will see when they view instances of this type in the user interface, therefore, the description should be meaningful.
Upload Schema
Optional. Specify a XML Schema Definition (XSD) file for the new resource.
Upload Files
Optional. Specify one or more input files for API.
You can use the Browse button to navigate to the required folder.
If you want to specify additional input files, use the plus button to create a new input field, and then use the Browse button to select another input file.
Parameters - Add Parameter (link)
Optional. Specify one or more request parameters of the following types at the Resource level:
*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 within the resource.
a. Click the Add Parameter link to open the Add Parameter dialog.
b. In this dialog, you define input parameters at the Resource level. To specify multiple parameters, click the Add Parameter link to add each new parameter.
The new parameter is added to the resource. For a complete description of how to add the request parameters, see Adding Parameter to REST API.
6. Expand the resource whose details you want to view.
7. To further update the new resource, mouse over the resource, and then click the Edit icon. Repeat for each resource that you want to modify.
8. To specify multiple resources, click the Add Resource link to add each new resource.
9. After you specify the value for all of the required fields, click the Save icon to save the changes.
Copyright © 2015- 2016 Software AG, Darmstadt, Germany.
Product LogoContact Support   |   Community   |   Feedback