Adding Parameter to REST API
Parameters are used to pass and add additional information to a request. You can use parameters as part of the URL or in the headers or as part of the message body.
Pre-requisites
Multiple parameter types exist - the most widely used parameters are path and query-string parameters.
Path parameters, which are integral part of the request URL and correspond to the URL path variable names.
The following example shows the path parameter representations and the result expected:
GET /phones/412456 - Returns the details for a specific phone whose product code is 412456.
In the above snippet, the URL path variable name 412456 is passed as a parameter to the GET method.
Note: | CentraSite allows you to define a path parameter only at the Resource level. |
Query-String parameters, which are passed as the request URL query parameters.
The following examples show the different query-string parameter representations and the results expected:
GET /phones?make=apple - Returns a list of all the phones that match the specified brand
Apple.
GET /phones/412456?format=JSON - Returns the details for phone whose product code is
412456 in the JSON format.
Header parameters, which are passed as custom HTTP headers.
The following example shows the header parameter representation:
GET /phones?412456
Accept-Encoding: application/json
x-CentraSite-APIKey:66f4b263-cc6e-11e3-85a7-a2d064a5bd02
Form parameters, which are encoded as the POST part of the request message body.
Important: | Although CentraSite allows you to define parameters of the type "Form" at the API level, these parameters are not supported at run-time. |
In this task, you define input parameters either at the API level, Resource level or Method level. Defining a parameter at the API level (in the Technical Details profile) means that it is inherited by all Resources, and by all methods under the individual Resources. Defining a parameter at the Resource level (in the Add Resource dialog box) means that it is inherited by all Methods under it. Defining it at the Method level (in the Add Method dialog box) only applies the parameters to that particular method; it does not affect either the API level or Resource level.
To add a parameter
2. In the actions bar for the API, click the Edit icon.
3. Select the Technical Details or Resource and Methods profile.
4. Expand the Parameters section in the Technical Details profile or the Add Resource dialog box or the Add Method dialog box, as required.
5. Click the Add Parameter link.
6. In the Add Parameter dialog box, enter the following information in the fields provided:
In this field... | Do the following... |
Name | Mandatory. Enter a display name for the parameter. |
Description | Optional. Enter a comment or descriptive information about the parameter. |
Parameter Type | Select a parameter type (Path, Header, Query-String, Form). For a list of the supported parameter types, see Parameter Types. |
Data Type | Select the parameter's data type. |
Required | Specify whether the parameter is mandatory or optional for invoking the REST API. |
Array | Specify whether the parameter can hold a just a single value or multiple values (an array of values). Enabling the Array option allows you to assign more than one value to the parameter. |
Possible Values | Optional. Enter a list of possible values for this parameter. |
Default Value | Optional. If you want to specify a default value, enter a value in this field. |
7. To further update the new parameter, mouse over the parameter, and then click the Edit icon. Repeat for each parameter that you want to modify.
8. To specify multiple parameters, click the Add Parameter link to add each new parameter.
9. If you need to delete a parameter, mouse over the parameter, and then click the Delete icon. Repeat for each parameter that you want to delete.
10. After you specify the value for all of the required fields, click the Save icon to save the changes.
