Viewing REST Service Details
Pre-requisites:
Make sure that you have the details page of a REST Service in the View mode to examine its details.
You use the details page of a REST Service to examine its RAML/Swagger documentation.
The REST Service asset type has a unique set of profiles. However, your administrator can configure the REST Service asset type to display a customized set of profiles and attributes.
The following general guidelines apply when examining the details of a REST Service in CentraSite Business UI:
If you are not the owner of a REST Service, you cannot view the details page of the REST Service unless you have a View permission on the REST Service (granted though either a role-based permission or instance-level permission).
You will only see profiles of the REST Service for which you have an instance-level View permission.
You can toggle the
Resources | Methods menu to display the details of a REST Service in either the
Resources view or the
Methods view.
In addition to examining the Resources and Methods of a REST Service, you can choose to delete one or more of the top level REST components - REST Resources or the REST Methods.
REST Service Compatibility
Beginning with version 9.7, CentraSite supports the enhanced interface for REST Services (in contrast, earlier versions of CentraSite supported a standardized interface for REST Service). Documentation of the prior REST Service interface is available to CentraSite customers who have a current maintenance contract in Empower Product Support website.
If you Migrate REST Services from a Pre-9.7 Release: If you have REST Services that were created prior to version 9.7, these REST Services will continue to hold the old version's metadata in the enhanced REST Service interface implemented by version 9.7 of
CentraSite.
If you Migrate REST Services from a 9.7 Release: If you have REST Services that were created in the
CentraSite version 9.7 using the
CentraSite Business UI, these REST Services will again continue to hold the version's metadata in the enhanced REST Service interface implemented by current version of
CentraSite. However, you will find the following information in the migrated REST Service:
The sample request and response messages that were shown under the REST Method display without changes.
The status codes that were shown under the REST Method will now display under the REST Response.
If you Migrate REST Services to 10.7 Release: If you have REST Services that were created in the
CentraSite version 9.7 using the
CentraSite Business UI, these REST Services will again continue to hold the version's metadata in the enhanced REST Service interface implemented by current version of
CentraSite. However, you will find the following information in the migrated REST Service:
The sample request and response message that existed under the Rest method will now display under the REST Response or REST Request content-type.
Inline schemas and Inline examples are displayed as REST Schema and REST Example.
Inline schema are now converted to Component schemas, and referred from request or response.
Inline schema with same content is shown as one schema.
Note:
Beginning with version 9.8, although CentraSite supports the existing REST Sample Requests and Responses, we enforce you use the REST Requests and REST Responses to specify additional details about the REST payload. You may use the Sample Requests and Responses if required.
Note:
Beginning with version 10.7, CentraSite supports REST Schema, REST Example, REST Links, and REST Callbacks.
CentraSite Business UI offers the Resource-Centric and Method-Centric views for examining the details of a REST Service.
Using the Method-Centric View
You can access the Method-Centric view by clicking on the Methods menu in the Resources and Methods profile.
The Method-Centric view displays the available HTTP methods for a REST Service. In a displayed REST Service, if there are HTTP methods defined at the Resource level, the Method-Centric view displays the list of all HTTP methods defined at the various Resource levels for that service. This view provides you a consolidated list of the supported HTTP methods for any given resource path URI. The default display is Method-Centric view.
In short, a Method-Centric view displays the details of a REST Service in the following hierarchical pattern:
..> HTTP Methods...
… > Resource Path, Name…
… > Method Description, Request Content Type, Response Content-Type ….
… > Method Parameters > Name, Type, Description…
… > HTTP Requests > Name, Description, Request Content-Type, Schema, Example…
… > HTTP Responses > Status Code, Name, Description, Response Content-Type, Schema, Example…
Using the Resource-Centric View
You can access the Resource-Centric view by clicking on the Resources menu in the Resources and Methods profile.
The Resource-Centric view displays the available resources for a REST Service. In a displayed REST Service, if there are multiple resources, and each resource defined with multiple HTTP methods, the Resource-Centric view displays all the REST components - Resources, Methods that apply to the selected Resource, and the Parameters, HTTP Requests, HTTP Responses, and Sample Requests and Responses that are defined at the various Method and Resource levels in that service. This view provides you a consolidated list of available resources for the displayed service.
In short, a Resource-Centric view displays the details of a REST Service in the following hierarchical pattern:
…> Resources …
… > Description, Resource Path, Resource Parameters, Documents, Schema, Callbacks…
… > HTTP Methods, Resource Path, Resource Name…
... > Description, Request Content Type, Response Content Type ….
… > Method Parameters > Name, Type, Description…
… > HTTP Requests > Name, Description, Request Content-Type, Schema, Example, Callbacks…
… > HTTP Responses > Status Code, Name, Description, Response Content-Type, Schema, Example, Callbacks…
Using the Components profile
You can access the component objects by clicking on the Components profile of the REST Service.
The Components profile displays the available component objects for a REST Service.
In short, the Components profile displays the component object details of a REST Service in the following hierarchical pattern:
…> Components …
… > Schemas …
… > Name, Description, Value…
… > Parameters …
… > Name, Description, Parameter Type, Data Type, Required, Array, Possible Values, Default Value…
… > Headers …
… > Name, Description, Data Type, Required, Array, Possible Values, Default Value…
… > Examples …
… > Name, Description, Value…
… > Links …
… > Name, Description, Request Body, Method, ParamName, ParamValues…
… > Callbacks …
… > Name, Resources, Parameters, Methods…
… > Requests …
… > Name, Description, Content Type, Schema, Example…
… > Responses …
… > Name, Description, Content Type, Schema, Example, Headers, Links…
In this task you examine the basic and type-specific attributes that are associated with a REST Service asset. You can view the resources, methods, and parameters in the Resources view and the Methods view.
To view the details of a REST Service asset
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 then follow these steps:
a. Click the chevron next to Assets option button.
A list of defined asset types in CentraSite is displayed.
b. In the displayed 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 asset you want to examine the attributes.
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.
You can hover over the info symbol next to an attribute to display the tooltip text, which describes the purpose of the attribute. The tooltip text displays the values of the attribute's Name and Description fields that are contained in the REST Service type definition.
6. Examine the generic attributes that are displayed in the Basic Information profile.
7. To examine the extended attributes that are displayed in the individual profiles, follow these steps:
a. Select the profile that contains the attribute(s) you want to display.
b. Examine the attributes on the profile as required.
c. Repeat steps 7.a and 7.b for each profile for which you want to display the details.
8. To examine the extended attributes that are displayed in the components of the REST Service - Schemas, Parameters, Headers, Examples, Links , Callbacks, Requests, and the Responses, click the Components profile.
This profile displays a list of currently defined Schemas, Parameters, Headers, Examples, Links , Callbacks, Requests, and the Responses in the components profile.
9. To examine the extended type-specific attributes of the REST Service - Resources, Methods, Parameters, Status Codes, and the Request and Response Messages, click the Resources and Methods profile.
This profile displays multiple attributes which are dependent on the Resource Centric view or Method Centric view.
10. To select the Resource-Centric view or the Method-Centric view, click the Resources | Methods menu on the upper right-side. Depending on the view selected, the profile displays a list of REST Resources, or REST Methods.
CentraSite Business UI displays a list of the currently defined Resources, or Methods based on the Resource-Centric view or Method-Centric view that you have selected.
11. Click the chevron next to the REST Resource's name to examine its details.
12. Click the REST Method's Name button to examine its details.
13. Drill down to different levels of the REST Parameters, HTTP Requests, HTTP Responses, Links, and the Rest Callbacks to examine the details of each of them.
14. Click the REST Parameter for which you want to display the details.
15. If you have made changes to a REST Parameter, click Save.