Planning for release compatibility with the Streams REST management API

You can design your application to avoid future compatibility issues due to updates to Streams REST management API.

Procedure

To plan for compatibility between releases:

  • Tolerate unknown content.

    Unknown content might be generated by servers that have a later release level. For example, new properties might be returned for an existing resource or new property values might be returned for an existing property. Design your application to ignore or handle any unexpected content in a manner that does not require you to rebuild the application.

  • Do not rely on failures for unexpected request content

    The Streams REST management API ignores unknown request content. For example, unexpected query parameters and unexpected query parameter values are ignored by the REST management API. Consider this behavior when you are debugging problems. If your application can handle the fact that some content might be ignored, it increases the likelihood that applications that were built for later release levels can access some information from servers that were implemented at earlier release levels.

  • Tolerate missing content.

    Check for the existence of a property in your resource response before you attempt to use its values, even if the property is not defined as an optional property. If a property is missing, use default processing or other handling methods that do not require you to rebuild the application.

  • Write the application to the HTTP interface

    Write your application to the HTTP interface rather than to the current Streams REST management API behavior. For example:

    • Use HTTP content negotiation to determine the content type. In Teracloud Streams, the REST management API supports content that uses the JavaScript Object Notation (JSON) format for most URIs. There are some URIs, however, that support different content types and support might be added for more content types in the future.
    • Tolerate any valid HTTP status codes. The status codes that are returned by the REST management API might change over time.
    • Supply valid HTTP request headers. If the header is ignored by Streams, it might not be ignored in future releases.
    • Tolerate any valid HTTP response headers. In future releases of Streams, the returned response headers might change.

  • Use the root uniform resource identifier (URI) to find other URIs.

    Use the response from the root URI https://server:port/streams/resources to find the other supported URIs.