Set resource path with WSParam and WSPath

Path parameters allow you to specify variables in the resource URL.

In the OpenAPI specification, path templates are the parts of the path that are replaceable with parameters. If you need to point to a specific resource within a collection (such as a user identified by ID) and when a pattern could match many similar resources, you use path templates in your REST function.

The OpenAPI specification denotes path templates within curly braces

{
}

/users/{id}

The path template {id} is substituted with actual values when a GWS client makes a call to the resource. In this example, the URI provides the user id "22":

http://myhost:6394/gas/ws/r/myGroup/myXcf/Account/users/22

With the URI, you have made a request of the resource. A function in your web service with the above path pattern processes the request.

The REST attributes WSPath and WSParam set in the attributes clause of the BDL function support path templating. WSPath may have many templates. For each input parameter with a WSParam attribute, there must be a matching template in the WSPath attribute value, otherwise compilation error-9111 is thrown.

For example, this WSPath has two templates, membersid and booksid:

ATTRIBUTES (WSGet,WSPath="/members/{membersid}/books/{booksid}")

It defines the path to a resource that returns details of a specified book checked out of a library by a specified user (see Example: access a resource from path set with templates). The input parameters of the function are described in Table 1.

Table 1. Path parameters
Input parameter with WSParam attribute	Description
`membersid INTEGER ATTRIBUTE(WSParam)`	A unique identifier for a library user resource.
`booksid INTEGER ATTRIBUTE(WSParam)`	A unique identifier for a book resource.

Example: access a resource from path set with templates

IMPORT  com

TYPE checkoutType RECORD
           booksId INT,
           title VARCHAR(100),
           author VARCHAR(100),
           m_name VARCHAR(100),
           checkout_date DATETIME YEAR TO SECOND
        END RECORD

DEFINE myrror RECORD ATTRIBUTE(WSError="My error")
  code INTEGER,
  reason STRING
END RECORD

PUBLIC FUNCTION getBooksCheckedOut(
   membersid INTEGER ATTRIBUTE(WSParam),
   booksid INTEGER ATTRIBUTE(WSParam) )
  ATTRIBUTES (WSGet,
              WSPath="/members/{membersid}/books/{booksid}",
              WSDescription="Get details when a library member checked out a specific book",
              WSThrows="400:Invalid,406:Should not happen" )
  RETURNS (
    DYNAMIC ARRAY ATTRIBUTE(WSName="Books_checked_Out",WSMedia="application/xml") OF checkouttype 
    ATTRIBUTE(XMLName="Book") )
    DEFINE bookList DYNAMIC ARRAY OF checkouttype
    INITIALIZE bookList TO NULL
    TRY
      DECLARE c1 CURSOR FOR SELECT b.booksid, b.title, b.author, m.name, c.checkoutdate
        FROM books b
        INNER JOIN checkouts c
        ON c.booksid = b.booksid
        INNER JOIN members m
        ON m.membersid = c.membersid
        WHERE c.booksid=booksid AND c.membersid = membersid
      IF sqlca.sqlcode = 0 THEN
        # ... function code
      END if
    CATCH
       CASE
          WHEN sqlca.sqlcode = NOTFOUND
            LET myerror.reason = SFMT("Nothing found for member: %1", membersid )
            CALL com.WebServiceEngine.SetRestError(400,myerror)
          OTHERWISE
            LET myerror.reason = SFMT("Error in SQL execution: %1 [%2]", sqlca.sqlcode, SQLERRMESSAGE )
            CALL com.WebServiceEngine.SetRestError(406,myerror)
        END CASE
    END TRY
    FREE c1
    RETURN bookList
END FUNCTION

In this URL example, the values "48" and "3" replace the variable parts of the path:

http://myhost:6394/gas/ws/r/myGroup/myXcf/MyLibrary/members/48/books/3

The XML output is customized by WSName and XMLName.

When to use WSParam or WSQuery

Know when to use WSParam or WSQuery attributes in your Web service.

Use a path parameter (with WSParam) to return a single entity given its id field.
For example, /users/{id} specifies the entity in the resource path. If the entity specified by the {id} path parameter is not found, you typically get a "404 (Not found)" HTTP response code.
Use a query parameter (with WSQuery) for any field other than a resource id. A number of entities may be returned in the response.
With a search or filter, you expect to return a number of entities in the response, unlike the single entity that you expect to get as the response for sending id as path parameter. WSQuery is the logical attribute to use for filtering, searching, or sorting resources.
For example, in /users?lastname=smith, the search criteria is specified in a query parameter of the URL. If no entities are found matching the search or filter parameters, you typically get a "200 (OK)" HTTP response code with an empty array as the response body.