Software AG Products 10.7 | Using CentraSite | Asset Management | Managing Assets through CentraSite Business UI | REST Service Management | Adding REST Service from Scratch
 
Adding REST Service from Scratch
 
Adding Endpoints to REST Service
Adding Components to REST Service
Adding Resource to REST Service
Adding HTTP Method to REST Service
Adding Parameter to REST Service
Adding Components Objects to Resources and Methods
Adding HTTP Request to REST Service
Adding HTTP Response to REST Service
Adding Status Code to REST Service
Pre-requisites:
To add a REST Service asset to an organization's asset catalog, you must belong to a role that has the Create Assets or Manage Assets permission for that organization.
Note:
By default, users with the CentraSite Administrator or Asset Administrator role have this permission.
Before you add a REST Service asset to the catalog, you must have the RAML, Swagger 2.0 or OpenAPI specification file that you want to import. This file can reside on the file system of the computer where your browser is running or it can reside anywhere on the network, as long as its location is addressable through a URL.
Now that we are familiar with the RESTful paradigm, let us focus on documenting a REST Service using the enhanced REST data model in CentraSite Business UI.
If you are documenting our sample online phone store application as a REST Service by capturing the metadata collected from online phone store application. The metadata to manage the latest phone details online will include the following:
*A list of resources. For example, phones.
*A list of HTTP methods the Service will support for each individual resource phones. For example, GET, POST, PUT, PATCH, and DELETE.
*A list of parameters that will best describe the resource phones. For example, features=androidosv4.3&cameraresolution=8MP
*A list of sample HTTP request and response messages.
The sequence of documenting a REST Service using the CentraSite Business user interface can be best understood with the following illustration:
*Start by defining basic details of a REST Service and then define the base URL, schemas, and parameters.
*Easily capture resources and methods and then add the required details as you want.
*Add parameters and other details (content types, status codes) specific to each call.
*Specify examples, schemas, and links for each request and then the corresponding examples, schemas, and links for the expected responses with respect to Content-Type.
*To add a REST Service asset from scratch
1. In the CentraSite Business UI activity bar, click Create Asset.
This opens the Create Asset wizard.
2. In the Basic Information profile, provide the required information for each of the displayed data fields.
Field
Description
Name
(Optional). Name of the REST Service.
Note:
This is the name that users will see when they view this REST Service asset in the CentraSite User Interfaces. Therefore, specify a meaningful name for each REST Service.
The name of a REST Service asset 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.
*Furthermore, if the REST Service name contains any non-conformant character, upon publishing the REST Service to any gateway, the non-conformant character is simply replaced with the underscore character (_) in Mediator. However, in CentraSite the REST Service name defined by you is displayed.
For more information about the NCName type, see http://www.w3.org/TR/xmlschema-2/#NCName
If you have not specified a Name for the REST Service, CentraSite automatically maps this field with the Service Title property, that is defined in the Swagger specification.
Type
The asset type, REST Service.
Organization
The organization to which you want to add the REST Service. (The Organization list only displays organizations for which you have the Manage Assets permission or at least the Create Assets permission.)
Version
(Optional). The version identifier for the REST Service. You can enter any string in this field, that is, the version identifier does not need to be numeric. You can also leave the field blank. You can later create new versions of the REST Service. The default is 1.0.
Examples:
0.0a
1.0.0 (beta)
Pre-release 001
V1-2007.04.30
If you have not specified a Version for the REST Service, CentraSite automatically maps this field with the Service Version property, which is defined in the Swagger specification.
Description
(Optional). The description for the REST Service.
Note:
This is the description information that users will see when they view this REST Service asset in the CentraSite User Interfaces. Therefore, specify a meaningful description for each REST Service.
If you have not specified a Description for the REST Service, CentraSite automatically maps this field with the Description property, that is defined in the Swagger specification.
Import from a Specification File
The input file for the REST Service.
Option
Description
URL
If the input file you are importing resides on the network, you can specify its URL.
File
If the specification resides in your local file system, specify the file name. You can use the Choose button to navigate to the required folder.
3. Click the Advanced Settings chevron to expand the additional options that are available for the Web Service asset. Provide the required information for each of the displayed fields:
Field
Description
Credentials
If you have specified a URL and the site you want to access through the URL requires user authentication, type a username and password for authentication at the URL site.
Resolution
Select a resolution strategy, which will allow you to specify how an already existing imported and included file is handled. For each of the imported and included files you have one of these options:
*Create new version: Creates a new version of the file with the new content (if, for example, you want to modify a WSDL file but want to retain its previous version).
*Always overwrite: Overwrites the importing file with new content.
4. Click Next.
You cannot navigate to the next screen unless all of its required attributes have been set.
5. In the Preview panel, review the basic information for the REST Service before you actually add to the CentraSite registry.
6. Click Save.
A REST Service asset instance is created in the specified organization and registered with the CentraSite registry/repository. The details page for the REST Service asset that you just created is displayed.
7. Configure the extended attributes of the REST Service asset as described later in this topic.