Defining and mapping headers, query parameters, or path parameters

You can add HTTP headers, query parameters, and path parameters to request messages and map them to various request fields. For response messages, HTTP headers can be added and mapped to various response fields.

If a parameter or header is an array, you must specify the data type in the array and the array format. The data type can be string, integer, boolean or number. The array format specifies the how the values in the parameter or header are delimited.

  • csv (comma-separated values)
    • Query parameter example: http://localhost:8080/v1/api/customer?id=1,2,3
    • Path parameter example: http://localhost:8080/v1/api/customer/1,2,3/policy
    • HTTP header example: X-ROUTE-CODE: ab,cd,wx,yz
  • ssv (space-separated values)
    • Query parameter example: http://localhost:8080/v1/api/customer?id=1%202%203
    • Path parameter example: http://localhost:8080/v1/api/customer/1%202%203/policy
    • HTTP header example: X-ROUTE-CODE: ab%20cd%20wx%20yz
  • tsv (tab-separated values): For query parameters and path parameters only.
    • Query parameter example: http://localhost:8080/v1/api/customer?id=1%092%093
    • Path parameter example: http://localhost:8080/v1/api/customer/1%092%093/policy
  • pipes (pipes-separated values)
    • Query parameter example: http://localhost:8080/v1/api/customer?id=1|2|3
    • Path parameter example: http://localhost:8080/v1/api/customer/1|2|3/policy
    • HTTP header example: X-ROUTE-CODE: ab|cd|wx|yz
  • multi (multiple parameter instances): For query parameters only.
    • Query parameter example: http://localhost:8080/v1/api/customer?id=1,id=2,id=3

Mapping rules for array type parameters and headers

For array type parameters and HTTP headers, note the following rules:
  • Because a parameter or header inherits constraints from the service field that they are mapped to, an array type parameter or header inherits the values for minimum items and maximum items from the service fields.
  • The HTTP element and the corresponding service field must have the same array depth (that is, they are nested within an identical number of array dimensions).
  • Only single-dimension arrays can be mapped to an HTTP header or parameter.

For more information, see Request and response mapping rules.

Request array parameter mapping example

The following example shows an API that allows adding a contact entry based on a unique last name.
Figure 1. A lastName path parameter that is defined in the API editor
This example shows a lastName path parameter that is defined in the API editor.
Based on the specified last name, the POST method would add the first name, middle name, address, and phone numbers. As shown in the following figure, middleNames, addressLines, and phoneNumber from the request are arrays of strings (string[]).
Figure 2. middleNames, addressLines, and phoneNumber as string arrays
This example shows the mapping of multiple array type query parameters.

Based on the following Swagger document of the API, multiple comma-separated middle names can be specified. The address are pipe-separated lines, and phone numbers can be multiple entries.

"post" : {
  "operationId" : "postPhonebookServiceJS.restclient",
  "parameters" : [ {
    "name" : "Authorization",
    "in" : "header",
    "required" : false,
    "type" : "string"
  }, {
    "name" : "lastName",
    "in" : "path",
    "required" : true,
    "type" : "string",
    "maxLength" : 60
  }, {
    "name" : "firstName",
    "in" : "query",
    "required" : true,
    "type" : "string",
    "maxLength" : 30
   }, {
    "name" : "middleNames",
    "in" : "query",
    "required" : false,
    "type" : "array",
    "items" : {
      "type" : "string",
      "maxLength" : 30
     },
    "collectionFormat" : "csv",
    "maxItems" : 7
  }, {
    "name" : "addressLines",
    "in" : "query",
    "required" : true,
    "type" : "array",
    "items" : {
      "type" : "string",
      "maxLength" : 100
    },
    "collectionFormat" : "pipes",
    "maxItems" : 9,
    "minItems" : 1
   }, {
    "name" : "phoneNumber",
    "in" : "query",
    "required" : true,
    "type" : "array",
    "items" : {
      "type" : "string",
      "maxLength" : 20
    },
    "collectionFormat" : "multi",
    "maxItems" : 5
  } ]
  "responses" : {
    "200" : {
      "description" : "normal response",
      "schema" : {
       "$ref" : "#/definitions/postPhonebookServiceJS.restclient_response_200"
      },
      "headers" : {
        "X-Status-Messages" : {
          "type" : "array",
          "items" : {
           "type" : "string",
           "maxLength" : 100
          },
          "maxItems" : 15,
          "collectionFormat" : "pipes"
        }
      }
    }
  }
}

A valid POST request would look as follows. 

POST https://<serverName>/<portNumber>/<apiName>/Doe?firstName=John&
middleName=J.,R.,Edgar&
addressLines=555%20Bailey%20Ave|San%20Jose,%20CA|95123&
phoneNumber=14081111111&phoneNumber=14082222222&phonenumber=14083333333

The response body would look as follows: 

{
  "ADDRESS_LINES": [
      "555 Bailey Ave",
      "San Jose, CA",
      "95123"
  ],
  "PHONE": [
    { 
      "PHONE_NUM": "14081111111" 
    },
    { 
      "PHONE_NUM": "14082222222" 
    },
    { 
      "PHONE_NUM": "14083333333" 
    }
  ],
   "LAST_NAME": "Doe",
   "FIRST_NAME": "John",
   "MIDDLE_NAME": [
      "J.",
      "R.",
      "Edgar"
   ],
}