Planning for release compatibility with the IBM Streams REST API

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 IBM Streams REST API ignores unknown request content. For example, unexpected query parameters and unexpected query parameter values are ignored by the REST 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 IBM Streams REST API behavior. For example:

  • Use HTTP content negotiation to determine the content type. In IBM Streams, the REST API supports only content that uses the JavaScript Object Notation (JSON) format. In future releases, however, support might be added for more content types.
  • Tolerate any valid HTTP status codes. The status codes that are returned by the REST API might change over time.
  • Supply valid HTTP request headers. If the header is ignored by IBM Streams, it might not be ignored in future releases.
  • Tolerate any valid HTTP response headers. In future releases of IBM 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/rest/resources to find the other supported URIs.