Using SAFS REST Testing API

Author: Carl Nagle
Update: Sep 07, 2016 CANAGL

Copyright, SAS Institute http://www.sas.com
General Public License (GPL):  http://www.opensource.org/licenses/gpl-license.php

  1. The SAFS REST Testing API

    Refer to the SAFS REST JavaDoc as part of this discussion for using this API.

    This framework is intended to streamline REST API testing code so that more is written by the tester that actually tests and verifies the target REST API rather than preparing, making, and evaluating the calls to that target REST API.

    The testing framework supports user-defined service "sessions" intended to persist important information for a REST service for reuse. This allows the tester to focus on the specifics of individual calls to that service.

  2. Defining External, Multi-Line Headers in Java Properties files

    In order to maximize reuse and reduce the code necessary to make a proper REST API call, we promote the concept of maintaining critical multi-line Header Strings in external Java Properties files.

    To take advantage of this for HTTP Headers, examples of the syntax for multi-line headers are shown below: 

        SampleHeaders: Retry-After: Fri, 31 Dec 1999 23:59:59 GMT       \r\n\
                   Some-Header: Some more spaces that are unquoted  \r\n\
                   Last-Modified: Tue, 15 Nov 1994 12:45:26 GMT

    MyJSONHeaders: Content-Type: application/myClass+json   \r\n\
                   Content-Length: 0                        \r\n\
                   Accept: application/myClass+json

    We are showing the line continuation as " \r\n\ " because the HTTP spec shows that CRLF ( \r\n ) is required to terminate a header and using either ‘ \r ’ or ‘ \n ’ by themselves may not be considered an appropriate line ending. Then the final ‘ \ ’ is the Java Properties line continuation character that must be followed by the real CRLF line-ending terminator.

  3. Storing Custom Headers for Repeated Use

    We recommend basing the Properties filename on the serviceId of the Service being tested.

    (PROPOSAL)

    When the Properties filename is based on the serviceId, and the Properties file is findable in the runtime CLASSPATH, then the framework will automatically locate and load the header types defined in the Properties file during the call to REST.StartServiceSession.

    By default, the automatic loading of Service default and/or custom header types in your Headers Properties file will invoke Headers.setHeadersForType for each name=value pair found in the Headers Properties file.

    The default Header "Types" which can be in the Properties file to override the defaults already supported should have specific predefined names of:

    If for any reason we cannot automatically find or load this default Properties file, the tester will need to load the Properties and call the appropriate Headers class methods for the types of Headers they wish to use or modify from their defaults. The tester may also need or want to change stored headers at runtime using the methods of the Headers class:

  4. Opening and Closing Server "Sessions"

    REST.StartServiceSession must be called prior to any attempts to use the testing framework to test a specific REST Service. The call prepares the system for finding the specific Service for each subsequent REST.GET, PUT, POST, etc. without the tester having to explicitly specify full path URIs (domains and ports) for every call to the Service. It also allows the system to automatically configure test framework internals for things like custom Content-Type and Accept headers that are specific to the Service being tested.

    The user-defined "serviceId" is used to uniquely identify the Service to be tested. It will also be used to automatically seek and load associated resources--like Header Properties files containing Service-specific headers and other info, if available.

    The returned Service object is where customizations to the REST service calls can be made--such as authentication information to be used, and explicit HTTP Protocol Version to be used.

    REST.EndServiceSession should be called to release any assets or resources associated with testing the Service once testing for the associated Service has been completed.

  5. Making Simple Calls for Predefined Accept: Content Types

    Use the REST class and its inner classes to make calls to exercise the target REST Service and evaluate the Response of those calls:

  6. Making Custom Calls using Complex Headers

    Fully custom calls can be accomplished via the REST.request method.