Text Analytics: Unified Language REST API Support

text-analytics-unified-language-support-proposal.md

Text Analytics: Unified Language REST API Support

Historically, Text Analytics has existed as a dedicated REST service in Azure, managed and evolved independently from other Cognitive Services offerings. This has led to developers working directly with the REST APIs having to learn unique locations, structure, and usage patterns for the different services, despite them having a similar goal of analyzing language-related aspects of documents.

Going forward, the Cognitive Services teams are consolidating REST APIs with related functionality into a single REST service. In the case of Text Analytics, service functionality is moving to a new unified language service. The API of the new unified language service introduces changes both structurally and behaviorally, making it incompatible with the API offered by the stand-alone Text Analytics REST service.

In order to support the unified language service, the client libraries will need to determine an approach able to accommodate the new REST API without introducing breaking changes to customers.

TLDR

The Text Analytics SDK team recommends supporting the two REST services side-by-side transparently in the current client within the same API.

Things to know before reading

• The names used in this document are intended for illustration only. Some names are not ideal and will need to be refined during discussions.

• Some details not related to the high-level concept are not illustrated; the scope of this is limited to the high level shape and paradigms for the feature area.

• Fake methods are used to illustrate "something needs to happen, but the details are unimportant." As a general rule, if an operation is not directly related to one of the Text Analytics types, it can likely be assumed that it is for illustration only. These methods will most often use ellipses for the parameter list, in order to help differentiate them.

Why this is needed

While the majority case for creating a client involves accepting the default service version defined by the options, some developers prefer to lock to a specific service version. For example, this scenario is often observed in enterprise environments where companies are conservative about possible behavioral changes and adopt new versions of the client library and service at different times to allow for testing them individually.

var options = new TextAnalyticsClientOptions(ServiceVersion.V3_0);    
var client = new TextAnalyticsClient(new Uri("<< ENDPOINT >>"), new AzureKeyCredential("<< KEY >>"), options);

In these scenarios, were the client library to stop supporting versions associated with the Text Analytics service REST API, breaking changes would be introduced to codebases requesting a specifc service version of the Text Analytics REST API. To ensure that we support the Azure SDK goal of limiting breaking changes outside of special justification, the client library will need to continue to support all previously available stable service versions.

Goals

• Allow developers to continue to use existing Text Analytics REST API versions while also allowing access to the Unified Language REST API.

• Preserve the existing Text Analytics developer experience to the largest extent possible; in the ideal case, developers should have no need to understand the change in REST services.

• Avoid creating developer confusion by introducing assets, terminology, and public APIs if at all possible; it is strongly desirable to not invalidate existing articles, samples, and documentation.

• Do not cause developer frustration and loss of trust by invalidating investments they have made to adopt the Azure.AI.TextAnalytics package, which was released only 18 months ago.

Option 1 (recommended): Support side-by-side REST APIs in the existing Text Analytics client

In this approach, the Azure.AI.TextAnalytics package and its public API surface do not change in an impactful way. The client library will support both the Unified Language service and Text Analytics service APIs, transparently proxying between them based on the requested ServiceVersion. For the majority case, developers who upgrade their client library package will implicitly opt-into using the Unified Language API. Developers requesting a specific version will implicitly target the correct service API based on the options that they provide.

Assumptions

• The Unified Language REST API supports the same operations available in the Text Analytics REST API.

• The Unified Language REST API does not introduce any major breaking changes that the client library would be unable to translate. For example, if the Unified Language REST API begins to require information for an operation that wasn't needed in the Text Analytics API, the client library may not be able to provide it without a breaking change.

• These assumptions hold for future evolution of the Unified Language REST API.

Benefits

• The Text Analytics development experience is preserved; the client library retains the API shape and patterns that were the result of a considerable design effort and extensive user testing.

• The existing knowledge that developers have is still relevant and there is no need to relearn terms, concepts, or patterns.

• The Text Analytics ecosystem is not fragmented. Existing articles, samples, and documentation remain valid and developers are not burdened with understanding which assets are valid and which should be ignored.

• Package upgrades are seamless; developers do not need to understand that they should look for a new package or to need to avoid upgrading.

• Migration from one REST API to the other can be accomplished seamlessly by changing a parameter in the options.

Considerations

• As the service API evolves, new members may be added to models and be supported only in newer service versions. This will require that information be validated against service versions. When interacting with the Text Analytics service REST models, the client library may need to perform validation for fields that cannot be mapped since they are unknown to the service. This deviates from the Azure SDK recommendation of preferring service validation.

  For example, assume that a new option is added for requests using the Unified Language REST API. When using the Text Analytics REST API, the option does not exist and would be silently ignored. To provide a good developer experience, it may be necessary for the client library to perform that validation.

  var options = new TextAnalyticsClientOptions(ServiceVersion.V3_0);    
  var client = new TextAnalyticsClient(new Uri("<< ENDPOINT >>"), new AzureKeyCredential("<< KEY >>"), options);
  
  var documents = new List<TextDocumentInput>
  {
      new TextDocumentInput("1", "Some text document")
      {
           Language = "en",
      },
      new TextDocumentInput("2", "Another text document")
      {
           Language = "es",
      }
  };
  
  var options = new TextAnalyticsRequestOptions 
  { 
      IncludeStatistics = true,
      EnableUnifiedLanguageApiEnhancement = true
  };
  
  // Throws NotSupportedException
  var response = client.RecognizeEntitiesBatch(documents, options);

• Terminology in the client library would continue to follow Text Analytics REST API patterns; concepts that were renamed for the Unified Language REST API will not reflect the new nomenclature.

Option 2 (not recommended): Create a parallel client API

In this approach, the Azure.AI.TextAnalytics package will support both the Unified Language service and Text Analytics service APIs using an independent set of types dedicated to each REST API. For the majority case, developers who upgrade their client library package will continue to use the Text Analytics REST API unless they explicitly refactor their implementation to use the new types. Developers requesting a specific version will need to know which set of types target the desired service API.

Assumptions

• There is enough differentiation in the naming between the Text Analytics REST API and Unified Language REST API that the client library could model types for both without name collisions.

• These assumptions hold for future evolution of the Unified Language REST API.

Benefits

• The Unified Language REST API can evolve without maintaining backwards compatibility with the Text Analytics REST API.

• The client library is free to introduce API changes for the initial release and can align with the revised nomenclature used by the Unified Language REST API.

• Package upgrades are seamless; developers do not need to understand that they should look for a new package or may need to avoid upgrading.

• Migration from one REST API to the other can be done gradually without introducing new dependencies, though it may lead to unclear code.

Considerations

• The Text Analytics ecosystem becomes fragmented. Existing articles, samples, and documentation would need to be duplicated, making discovery more difficult and likely causing confusion.

• Developers will need to interpret articles, samples, and documentation to determine which set of types or approach is best suited for their application scenarios and understand how to make that decision.

• Discovery of types and functionality within the client library becomes difficult. Developers exploring via code completion lists would be presented with a potentially overwhelming set of choices and little context to understand which types are used together.

• Updating the application to change the REST API used requires a non-trivial effort and relearning of types.

• We're effectively creating an embedded "track three" experience, though avoiding a direct package change. Customers who moved to Azure.AI.TextAnalytics over the last 18 months when it was first released are likely to feel a sense of frustration and loss of trust by being asked to migrate their applications again.

• The client library API would have multiple ways to accomplish the same scenario which likely are very similar to one another, burdening developers with attempting to understand when to choose one over the other.

  For example, consider the following hypothetical scenario:

  Text Analytics API

  var credential = new AzureKeyCredential("<< KEY >>");
  var options = new TextAnalyticsClientOptions();    
  var client = new TextAnalyticsClient(new Uri("<< ENDPOINT >>"), credential, options);
  
  var documents = new List<TextDocumentInput>
  {
      new TextDocumentInput("1", "Some text document")
      {
           Language = "en",
      },
      new TextDocumentInput("2", "Another text document")
      {
           Language = "es",
      }
  };
  
  var options = new TextAnalyticsRequestOptions 
  { 
      IncludeStatistics = true
  };
  
  var response = client.RecognizeEntitiesBatch(documents, options);

  Unified Language API (simulated for illustration)

  var credential = new AzureKeyCredential("<< KEY >>");
  var options = new CognitiveLanguageTextClientOptions();   
  var client = new CognitiveLanguageTextClient(new Uri("<< ENDPOINT >>"), credential, options);
  
  var documents = new List<CognitiveLanguageAnalyzeDocument>
  {
      new CognitiveLanguageAnalyzeDocument("1", "Some text document")
      {
           Language = "en",
      },
      new CognitiveLanguageAnalyzeDocument("2", "Another text document")
      {
           Language = "es",
      }
  };
  
  var options = new CognitiveLanguageAnalyzeRequestOptions 
  { 
      IncludeStatistics = true,
      TextRecognitionMode = TextRecognitionMode.Neural
  };
  
  var response = client.RecognizeEntities(documents, options);

Option 3 (not recommended): Create a new package

In this approach, the Azure.AI.TextAnalytics package will continue to be dedicated to the Text Analytics service API. A new package will be introduced which will exclusively support the Unified Language service API. For the majority case, developers who upgrade their client library package will continue to use the Text Analytics REST API; using the Unified Language REST API will require them to explicitly change to the new package and refactoring their implementation. Developers requesting a specific version will need to know which package targets the desired service API.

Benefits

• The Unified Language REST API can evolve without maintaining backwards compatibility with the Text Analytics REST API.

• The client library is free to introduce API changes for the initial release and can align with the revised nomenclature used by the Unified Language REST API.

• There is a clear and clean segmentation between the client libraries used for each service; once developers choose an SDK package, there are a single set of types available.

• Migration from one REST API to the other can be done gradually by referencing both packages, though it may lead to unclear code.

Considerations

• The Text Analytics ecosystem becomes fragmented. Choosing between packages is potentially unclear; developers will need to interpret documentation to understand that there are two similar packages, what the purpose of each is, and in what scenarios they would prefer which package.

• Changing packages requires a non-trivial effort and relearning of types.

• The majority of developers are not likely to care about which service they're using, only their application scenarios. This negates the benefit of having a clear segmentation.

• Existing articles, samples, and documentation would need to be duplicated, making discovery more difficult and likely causing confusion.

• We're effectively creating a "track three" experience; customers who moved to Azure.AI.TextAnalytics over the last 18 months when it was first released are likely to feel a sense of frustration and loss of trust by being asked to migrate their applications again.

References and Related

• Azure.AI.TextAnalytics API View (v5.2.0-beta.2)

• Unified Language Service Overview

• Unified Language Service REST API Overview

• Unified Language REST API Spec (2022-02-01-preview)

• Text Analytics REST API Spec (3.2-preview.2)

Option 3a: Major version update for Azure.AI.TextAnalytics
Similar considerations/benefits as option 3 but no new package in the package manager. This will ensure we have a single package and users will pick the latest major version to start that uses the unified language APIs.

@srnagar: The reason that wasn't included is that it would constitute a breaking change, which we were trying to avoid.

@jsquire this was the option we took for Form Recognizer when their REST APIs introduced breaking changes. Not saying we should do the same here but worth discussing in arch board today.