What is the functionality of the 'Located In' drop down for parameters in the Paths section of an API

On Demand Consulting
Author: Volodymyr Sitarchuk
Reviewer: Werner Tod

What is the functionality of the 'Located In' drop down indicated in the attached screenshot?

The following picture shows a path definition for a given API in API Connect:



In the "Located in" drop-down field you define where the parameter can be found in the call of the operation that is specified by the path.
The definition of operations in API Connect is based on the OpenAPI (aka. Swagger) specification a representation of the RESTful API standard.

For more details please see the description of possible values for the "Located in" field from the OpenAPI (Swagger) specification version 2.0 :
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#parameterObject:

 

• Path - Used together with Path Templating where the parameter value is actually part of the operation's URL. This does not include the host or base path of the API. For example in/items/{itemId} the path parameter is itemId.
• Query - Parameters that are appended to the URL. For example in/items?id=### the query parameter is id.
• Header - Custom headers that are expected as part of the request.
• Body - The payload that's appended to the HTTP request. Since there can only be one payload there can only be one body parameter. The name of the body parameter has no effect on the parameter itself and is used for documentation purposes only. Since Form parameters are also in the payload body and form parameters cannot exist together for the same operation.
• Form - Used to describe the payload of an HTTP request when either application/x-www-form-urlencodedmultipart/form-data or both are used as the content type of the request (in Swagger's definition the consumes property of an operation). This is the only parameter type that can be used to send files thus supporting the file type. Since form parameters are sent in the payload they cannot be declared together with a body parameter for the same operation. Form parameters have a different format based on the content-type used (for further details consult http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4):
  • application/x-www-form-urlencoded - Similar to the format of Query parameters but as a payload. For example foo=1&bar=swagger - both foo and bar are form parameters. This is normally used for simple parameters that are being transferred.
  • multipart/form-data - each parameter takes a section in the payload with an internal header. For example for the header Content-Disposition: form-data; name="submit-name" the name of the parameter is submit-name. This type of form parameters is more commonly used for file transfers.

The following IBM documentation gives details about the Body and Path types:
http://www.ibm.com/support/knowledgecenter/SSFS6T/com.ibm.apic.toolkit.doc/task_APIonPrem_defineapiresources.html:

c. In the Located In field select where the parameter is found in the call of your operation.
d. Optional: If you selected Path in the previous step you must define the location of the parameter in the Path field in the following form:
    /Path_Segment_1/{Parameter}/Path_Segment_2
    where:
       * the Path_Segment variables are the names of your path segments.
      * Parameter is the name of your parameter. It must match the name used to define it in step 9.b
e. Optional: In the Description field provide a description of your parameter.
f. Use the Required check box to specify whether the parameter is required for a call to be valid.
g. Optional: From the drop-down list for Type select the type of data that the parameter is expected to have when the call is received by API Connect. If you have set Located In  to  Body then you can select a JSON schema that you have defined for your API. For more information about creating JSON schemas see Step 22 of Composing a REST API.


Note that
a)
Up to version 5.0.7.2) API Connect supports OpenAPI (Swagger) 2.0. The draft 3.0 specification has other possible values for 'Located in' field as described here:
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#parameterObject
b)
The "application/x-www-form-urlencoded"  as well as the "multipart/form-data"  content types are not supported yet.
So the "Form" parameter type cannot be used as expected in the current version of API Connect.
See details in the following Knowledge Library article:
Support of web form in API Connect : HTTP POST requests with "application/x-www-form-urlencoded" and ?"multipart/form-data"  content types