Working with Path and Query Parameters

Path and query parameters are supported in ActiveMatrix BusinessWorks REST APIs. Path parameters can be applied only at the root level when they apply to all operations. They cannot be defined for individual operations only. Query parameters can be applied at root as well as at individual operation level.

Define parameters in the resource service path by enclosing each parameter in { } brackets. For example, to define the path parameter isbn for a book resource, specify the resource path as follows:

/book/{isbn}

In this example, the client would invoke this service using the URL http:/<host>:<port>/book/<isbn>.

Note: Path parameters that are not immediately enclosed in forward slashes are supported. For example, the parameter authorName('{isbn}') in the resource service path /book/authorName('{isbn}')/ is not directly contained by forward slashes, but will still successfully pass.

Insert a question mark (?) after a parameter to add query parameters to a resource. In the following example, isbn is defined as a query parameter, instead of the path parameter, in the resource service path:

/book?{isbn}

Insert (&) to use it as a delimiter when defining multiple query parameters. In the following example, the query parameters isbn and authorName are defined in the resource service path:

/book?{isbn}&{authorName}

All the parameters defined in the resource service path are made available to the user as Input for every operation. See the following image for the /book/{isbn} example to see the Input for the GET operation.



Important: Path parameter names and query parameter names must be unique in a resource service path. For example, the following path and query parameters is not supported:

/books/{isbn}?{isbn}

If the Request Format for a REST Binding is Form, the parameter name must be different from all element names in the referenced schema. For example if a Books schema contains the element isbn, isbn can not be used as query or path parameter name.

Important: Do not use the word "fields" as the name of a query parameter. The word "fields" is a reserved keyword for internal use. For example, to extract the author, isbn, and price fields from an instance of a book object with name Emma:

use: /books/Emma?author,isbn,price

not: /books/Emma?fields=author,isbn,price

Adding or Editing Path Parameters

You can create or modify path parameters for REST services that were created in the TIBCO Business Studio for BusinessWorks using an XSD. For REST services that were created using a Swagger file that was imported from an external source, you can only view the parameters that its operations support. You cannot create or modify the parameters for such services.

To create a path parameter, do the following:

Procedure

  1. Click Components under the Module Descriptors to open the Component Configurations page.
  2. Expand the Component<application_name> node.
  3. Double-click the process name (with the green chevron next to it) to open its properties.
  4. Click the Bindings tab.
  5. Append the path parameter to the Resource Service Path. For example, to define the path parameter isbn for a book resource, specify the resource path as /book/{isbn}.
  6. Click the green check mark button at the end of the text box to save your edits.
    The newly created path parameter appears in the Path Parameters table. You can edit the name of the parameter by clicking on it. You can change its type by clicking on it and selecting a new type from its drop-down menu. Be aware that these buttons will be disabled if you are viewing operations for an API that was created outside the TIBCO Business Studio for BusinessWorks and imported into the TIBCO Business Studio for BusinessWorks.

Adding or Editing Query Parameters

You can create or modify query parameters for REST services that were created in the TIBCO Business Studio for BusinessWorks using an XSD. For REST services that were created using a Swagger file that was imported from an external source you can only view the parameters that its operation supports. You cannot create or modify the parameters in such services.

To create a query parameter, do the following:

Procedure

  1. Click Components under the Module Descriptors to open the Component Configurations page.
  2. Expand the Component<application_name> node.
  3. Double-click the process name (with the green chevron next to it) to open its properties in the Properties view.
  4. Click the Bindings tab.
  5. Click an operation name in the Operations section.
  6. Click the Request tab in the Operation Details section.
  7. Click the green icon () to add a query parameter. To edit the parameter name click on the newly created parameter's default name and type in a new name. Be aware that these buttons will be disabled if you are viewing operations in an API that was created outside the TIBCO Business Studio for BusinessWorks and imported into the TIBCO Business Studio for BusinessWorks.
  8. You can also edit the existing query parameter to make it required or optional by clicking in the cell that corresponds to the parameter in the Required column. The value toggles from Yes to No or vice versa.