Hello Part 2 (add input Path parameter)

This example will add an input path parameter to the Hello World Example. If you have not completed the Hello World Example yet go back and complete it first.

Open the papihello workspace and the hellowworld.api.json API file.

Input Parameters

There are 4 different types of input parameters for REST APIs, Path parameters, Query parameters, Header and Body parameters.

Header parameters

Header parameters are included in the request header. Usually, the header just includes authorization parameters that are common across all endpoints.

Path parameters

Path parameters are part of the endpoint itself and are not optional. For example, in the following endpoint, {user} and {bicycleId} are required path parameters:

^{/service/myresource/user/{user}/bicycles/{bicycleId}}

Query string parameters

Query string parameters appear after a question mark (?) in the endpoint. The question mark followed by the parameters and their values is referred to as the “query string.” In the query string, each parameter is listed one right after the other with an ampersand (&) separating them. The order of the query string parameters does not matter.

For example:

^{/surfreport/{beachId}?days=3&units=metric&time=1400}

and

^{/surfreport/{beachId}?time=1400&units=metric&days=3}

would return the same result.

Request bodies

Frequently, with POST requests (where you’re creating something), you submit a JSON object in the request body. This is known as a request body, and the format is usually JSON. This JSON object may be a lengthy list of key-value pairs with multiple levels of nesting.

For example, the endpoint may be something simple, such as /surfreport/{beachId}. But in the body of the request, you might include a JSON object with many key-value pairs, like this:

^{{
"days": 2,
"units": "imperial",
"time": 1433524597
}}

Note: In OpenAPI v2.0, request bodies were classified as a type of parameter, but in v3.0, they are not considered a parameter but rather a path property.

For this example will will add a Path parameter that will be used to pass in a name that will be concatenated into the response message.

Add Input Path Parameter

Path parameters are added by adding a colon followed by the name of the parameter into the HTTP Path property.

In the lower right panel on the General Info tab edit the HTTP Path property to /helloworld/:name

Save the changes

After saving you will see that the Input Parameters tab now includes the Name parameters and that it is marked required

If you double click this parameters you will notice that the edit parameter dialog is limited. This is because the Name of the parameter is set by the Path value and the Path parameters are always required. You can change the data type and add example and description values.

Logic

To edit the existing Create Hello World response step, click on the Edit icon.

In the value for the response parameter click the blue triangle to the right to drop down a list of optional values. Click the API Input section to expand it and click on input{"name"].

The Hello World message will be replaced by a placeholder for the Name input parameter.

Now position your cursor before the placeholder and enter 'Hello ' + on the line and click OK.

Save the changes

Test

Switching to the Test tab you will notice there is now a text box to enter the value for the Name Path Parameter. If you added an example value it will autofill for you. Type whatever you like for the name and click Execute.

The response will now include the name that was passed in

Like with the Hello World Example, this example can be tested in the browser