Service annotation

1  @service

The @service annotation can be applied only to the main composite of a Teracloud® Streams application. This annotation is optional and is not required to enable the data exchange support. It is often used in conjunction with the @endpoint annotation to provide overarching documentation on a collection of endpoints that are exposed by an application.

For more information about Teracloud® Streams data exchange support, see Enabling Streams data exchange.

The SPL compiler reports errors when a @service annotation is applied in the following situations:

• When @service is placed on any operator that is not the application main composite.
• When JSON validation fails on any parameters that require JSON object content.

Optional elements

title

A short title for the API set. The type of the parameter is rstring.

externalDocsURL

A URL to additional documentation for the API set. The type of the parameter is rstring.

externalDocsDescription

A short description of the target documentation that is referenced by the externalDocsUrl parameter. The type of the parameter is rstring.

tags

A set of tags that can be used to logically group APIs. The type of the parameter is rstring. The format of the value is a JSON object with embedded quotes escaped. Each object property name specifies a tag name. The corresponding property value is a JSON object that contains tag metadata. The following metadata properties are supported:

• description: A short description of the tag grouping. The type of the parameter is rstring.
• externalDocs: Information about external documentation that is related to the tag grouping. The type of the parameter is object. The following properties are supported:
  • url: A URL to additional documentation for the tag. The type of the parameter is rstring.
  • description: A short description of the target documentation that is referenced by the url parameter. The type of the parameter is rstring.

description

A short description of the API set. The type of the parameter is rstring.

version

The version of the API document.

For more information about these parameters, see the OpenAPI Specification with a focus on the descriptions of the OpenAPI, Info, and External Documentation objects.

Example

@service (title="Stock Quote Service", 
          externalDocsUrl="https://mycompany.com/stockapp/doc", 
          externalDocsDescription="Stock quote service documentation", 
          tags="{\"Input\": {
                    \"description\": \"Endpoints for inserting data.\",
                    \"externalDocs\": {
                      \"url\": \"https://mycompany.com/stockapp/input/doc\",
                      \"description\": \"Documentation for inserting data.\"         
                    }
                 },
                 \"Output\" : {
                    \"description\": \"Endpoints for retrieving data.\",
                    \"externalDocs\": {
                      \"url\": \"https://mycompany.com/stockapp/output/doc\",
                      \"description\": \"Documentation for retrieving data.\"         
                    }
                  }
                }",
          description="This application ingests stock quote data and retrieves ticker averages over time.",
          version = "1.0.0.0")