Adding Components to REST Service

An API may have several common component objects, such as schemas, links, callbacks, requests, responses, parameters, example, and headers. You can use these component objects throughout the API by adding references where required.

The Components profile allows you to add reusable elements that you can use in the resources and methods. You can place such common elements in the Components section and reference them using the $ref variable. You can add the following global elements:

Schemas: A Schema represents the REST Schema objects, and provides the input and output data types serving as the structure (For example: JSON) for the request and response payloads for REST APIs. The schema specified here can be reused in the resource and method, component specifications across multiple resources and methods.

Parameters: A Parameter specifies REST Parameter objects, and represents the parameters at the resource or method level. Creating parameters under the Components profile allows you to reuse the parameter object throughout the API.

Headers: A Header specifies REST Parameter objects, and represents the headers of a response or a REST Encoding object. You can define parameters that can be reused as header parameters at the API, method, and response levels. Creating headers under the Components profile allows you to reuse the parameter object throughout the API.

Examples: A Example specifies REST Example objects, and represents the examples of a REST Schema or a REST MediaType object. Creating examples under the Components profile allows you to reuse the parameter object throughout the API.

Links: Links allow the developer of the native API to define the relationship and traversal mechanism between a response and other operations. You can include links to other methods that are related to the response. Creating links under the Components profile allows you to reuse the parameter object throughout the API.

Callbacks: A callback is an asynchronous API request that originates from the API server and is sent to the client in response to an earlier request sent by that client. You can define callback methods in this page and include them in the callback section of the methods that use it. Creating callbacks under the Components profile allows you to reuse the parameter object throughout the API.

Requests: A Request specifies REST Payload objects, and represents the request body of the REST Method. Creating requests under the Components profile allows you to reuse the parameter object throughout the API.

Responses: A Response specifies REST Payload objects, and represents the responses of a REST Method. Creating responses under the Components profile allows you to reuse the parameter object throughout the API.

To add Components to REST Service

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 Components.

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 Components profile.

a. In the Schemas section, click Add Schema and provide the following information:

Field	Description
Name	Name of the schema.
Description	Description of the schema.
Value	Specifies the value of the schema. Note: The schema value should be in JSON format. Other formats or invalid schema values is not exported, when generating OAS Specification file.

Click OK to add the schema component.

b. In the Parameters section, click Add Parameter and provide the following information:

Field	Description
Name	Name of the parameter.
Description	Description of the parameter.
Parameter Type	Specifies the parameter type. Available values: Path, Query-string, Header, and Form.
Data type	Specifies the data type. Available values: IP Address, Email, Number, Date/Time, URL/URI, Duration, String, and Boolean.
Required	Specifies the parameter is required if selected. Note: For Path parameter type , selecting Required is mandatory.
Array	Select if the input parameter is of type array.
Possible Values	Specifies the possible values for the parameter.
Default Value	Specifies the default values for the parameter.

Click OK to add the parameter component.

c. In the Headers section, click Add Header and provide the following information:

Field	Description
Name	Name of the parameter.
Description	Description of the parameter.
Data type	Specifies the data type. Available values: IP Address, Email, Number, Date/Time, URL/URI, Duration, String, and Boolean.
Required	Specifies the parameter is required if selected.
Array	Select if the input parameter is of type array.
Possible Values	Specifies the possible values for the parameter.
Default Value	Specifies the default values for the parameter.

Click OK to add the header component.

d. In the Examples section, click Add Example and provide the following information:

Field	Description
Name	Name of the example.
Description	Description of the example.
Value	The content of the example for request or response in JSON format.

Click OK to add the example component.

e. In the Links section, click Add Link and provide the following information:

Field	Description
Name	Name of the link.
Description	Description of the link.
Request Body	Payload of the request sent to the target operation.
Method	Specifies the reference to another REST method. This enables the response to navigate to the specified REST Method.
ParamName	Name of the parameter that needs to be passed as a parameter to the target operation.
ParamValues	Value for the parameter. Click + to add the parameter. You can additional parameters if required.

Click OK to add the link component.

f. In the Callbacks section, click Add Callback and provide the following information:

Field	Description
Name	Name of the callback.
Resources - Add Resource (link)	Click Add Resource and provide the following information: a. Resource Name: Name of the resource. This is the display name of the resource and resource path is used for execution. b. Resource Path: Specifies the path of the resource. The resource path should contain a "/". c. Description: Description of the resource.
Parameters - Add Parameters (link)	Click Add Parameter and provide required parameter information. The procedure for defining the parameters is given in Step 7b.
Methods - Add Method (link)	Click Add Method and for each supported method that you have added for a resource, provide the following information: a. Name: Name of the resource. This is the display name of the resource and resource path is used for execution. b. Description: Description of the method. c. HTTP Method: The HTTP operation you want to perform on the REST Resource. Available methods: CONNECT, DELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT, and TRACE. d. Request Content-Type: The content format for request message. (The Request Content-Type displays a list of the supported content formats for the REST Service.) By default, this field shows an empty value. e. Response Content-Type: The content format for response message. (The Response Content-Type displays a list of the supported content formats for the REST Service.) By default, this field shows an empty value. f. Deprecated: (Optional). Specify if the REST Method is deprecated. g. Add Parameter: Provide the required parameter information. The procedure for adding Parameter information is given in Step 7b. h. Add Request: Provide the required request information. The procedure for adding Request information is given in Step 7g. i. Add Response: Provide the required response information. The procedure for adding Response information is given in Step 7h.

Click OK to add the callback component.

g. In the Requests section, click Add Request and provide the following information:

Field	Description
Name	Name of the Request.
Description	Description of the Request.
Request Content - Add Request Content (link)	Click Add Request Content and provide the following information: a. Request Content-type: The content format for request message. (The Request Content-Type displays a list of the supported content formats for the REST Service.) By default, this field shows an empty value. b. Schema: Provide Name, Description, and Value for the schema. The procedure for adding Schema information is given in Step 7a. You can also select an existing schema. To select an existing schema: a. On the Add Request Content dialog box, click Choose. b. On the Choose a Schema dialog box, enter search text and click the search icon. c. A list of schemas is displayed. Select the desired schema and click OK. d. Add schema dialog box appears with the schema details. e. Click OK. c. Example: Click Add Example and provide Name, Description, and Value for the example. The procedure for adding Example information is given in Step 7d. You can also select an existing example. To select an existing example: a. On the Add Example dialog box, click Choose. b. On the Choose a Example dialog box, enter search text and click the search icon. c. A list of examples is displayed. Select the desired example and click OK. d. Add example dialog box appears with the example details. e. Click OK.

Click OK to add the request component.

h. In the Responses section, click Add Response and provide the following information:

Field	Description
Name	Name of the Response.
Description	Description of the Response.
Response Content - Add Response Content (link)	Click Add Response Content and provide the following information: a. Response Content-type: The content format for response message. (The Response Content-Type displays a list of the supported content formats for the REST Service.) By default, this field shows an empty value. b. Schema: Provide Name, Description, and Value for the schema. The procedure for adding Schema information is given in Step 7a. You can also select an existing schema. To select an existing schema: a. On the Add Request Content dialog box, click Choose. b. On the Choose a Schema dialog box, enter search text and click the search icon. c. A list of schemas is displayed. Select the desired schema and click OK. d. Add schema dialog box appears with the schema details. e. Click OK. c. Example: Click Add Example and provide Name, Description, and Value for the example. The procedure for adding Example information is given in Step 7d. You can also select an existing example. To select an existing example: a. On the Add Example dialog box, click Choose. b. On the Choose a Example dialog box, enter search text and click the search icon. c. A list of examples is displayed. Select the desired example and click OK. d. Add example dialog box appears with the example details. e. Click OK.
Headers - Add Header (link)	Click Add Header and provide the required header information. The procedure for adding Header information is given in Step 7c. You can also select an existing header. To select an existing header: a. On the Add Header dialog box, click Choose. b. On the Choose a Header dialog box, enter search text and click the search icon. c. A list of headers is displayed. Select the desired header and click OK. d. Add header dialog box appears with the header details. e. Click OK.
Links - Add Link (link)	Click Add Link and provide the required link information. The procedure for adding Link information is given in Step 7e. You can also select an existing link. To select an existing link: a. On the Add Link dialog box, click Choose. b. On the Choose a Link dialog box, enter search text and click the search icon. c. A list of links is displayed. Select the desired link and click OK. d. Add link dialog box appears with the link details. e. Click OK.

Click OK to add the response component.

8. Click Save.