Set resource path with WSParam and WSPath

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

Path parameters are variable parts of a resource path. You would use them if you needed in your function 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. This is an example of the format of a resource path with path template.

/users/{id}

In the OpenAPI specification, the parts of the path that are replaceable with parameters are path templates. They are denoted with curly brackets {}. The path template is substituted with actual values when a GWS client makes a call to the resource.

For instance, if a client requests data for a specific user, the user id (22) is provided in the URI:

http://host:port/gas/ws/r/group/xcf/Account/users/22

A function in your web service with the path pattern above processes the request.

In GWS REST the WSPath and WSParam attributes support path templating. Path parameters are set in the attributes clause of the function with the WSPath attribute. For example:

ATTRIBUTES (WSGet,WSPath="/members/{membersId}/books/{bookId}")

A call to the function with this path checks if a specified member checked out a book from the library. The input parameters that correspond to the templates in the path are described in Table 1.

Table 1. Path parameters
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.

Be aware that for each BDL function input parameter with a WSParam attribute, there must be a matching template value in the WSPath attribute value. fglcomp checks to ensure that there is one template value per parameter, otherwise compilation error-9111 is thrown.

Example path templating with WSPath and WSParam

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 myError RECORD ATTRIBUTE(WSError="My error")
  code INTEGER,
  reason STRING
END RECORD

PUBLIC FUNCTION getBooksCheckedOut(
    p_membersid INTEGER ATTRIBUTE(WSParam) )
  ATTRIBUTES (WSGet, 
              WSPath="members/{p_membersid}/books/",
              WSDescription="Get books checked out by a given member of the library",
              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 b.booksid = c.booksid AND c.membersid = m.membersid
        INNER JOIN members m
        ON c.membersid = p_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", p_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

The variable part of the path is replaced by the value /48/ in this URL example:

http://host:port/gas/ws/r/group/xcf/MyLibrary/members/48/books

The XML output is customized by WSName and XMLName.

When to use WSPath or WSQuery

It is important to know when it is appropriate to use these attributes in your Web service. Basically the difference is that a path parameter is used to return a single entity given its id field, while a query parameter is used for any other field other than a resource id and a number of entities may be returned in the response.

For example, /users/{id} specifies the entity in the resource path. Usually you get a HTTP response code 404 (Not found) if an entity is not found by the id specified as path parameter.

On the other hand if you think in the case of 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. Therefore, 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.

Usually you get an HTTP response code 200 (OK) with an empty array as the response body, if no entities are found matching the search or filter parameters.