Skip to content

Migration Guide

Jump to bottom Edit New page
Anwesha edited this page Nov 30, 2017 · 46 revisions

Version 3.0 Release Migration Guide

This guide will highlight the major changes in the SDK and how to update your code accordingly. This release contains new usage patterns for a lot of service. Old usage patterns should still be functional in this release; however, in the next major release, your code will be mandated to use those new usage patterns.

In this major release, several services have been generated from Swagger specifications of our services. Furthermore, the language has changed from NodeJS to TypeScript for these services. The change of language to TypeScript will not have an impact on NodeJS usage because the published public package contains NodeJS that is the result of transpiling the TypeScript code.

The following services are now being generated programmatically:

  • Conversation
  • Discovery
  • Language Translator
  • Natural Language Classifier
  • Natural Language Understanding
  • Personality Insights
  • Text to Speech
  • Tone Analyzer
  • Speech to Text
  • Visual Recognition

It's important to note that with so many of the services being moved to automated generation, there are many minor changes to method names, parameter names, etc. Therefore, this list is not exhaustive. However, we hope that this new approach will result in more consistent, maintainable code going forward.

Directory and Files

In each specific project directory the previous structure was something like

  • node-sdk/discovery
    • v1.js

This has been replaced with something like

  • node-sdk/discovery
    • v1.ts
    • v1-generated.ts

Where v1.ts is an adapter and v1-generated.ts is the new generated code. After building, there will be compiled files v1.js and v1-generated.js which are the JavaScript compilations of the TypeScript files.

Non generated code and helper methods are found in the /lib folder.

Adapters

Adapters are provided to ensure your old code will not break. These adapters follow the conventions of the v2 NodeSDK such as method names, parameters, etc. and call upon the generated code.

These are named for example for discovery: v1.ts Generated files follow the convention v1-generated.ts

These adapters should not be relied on and will not be supported for future versions and your code should be migrated to use the generated code.

Breaking changes in specific services

Conversation

getIntents

  • getIntents method renamed to listIntents

getDialogNode

  • optional export parameter removed

getExamples

  • getExamples method renamed to listEntities

getValues

  • getValues method renamed to listValues

getSynonym

  • optional export parameter removed

getSynonyms

  • getSynonyms method renamed to listSynonyms

getDialogNodes

  • getDialogNodes method renamed to listDialogNodes
  • optional export parameter removed

getLogs

  • getLogs method renamed to listLogs

getCounterExamples

  • getCounterExamples method renamed to listCounterExamples

updateIntent

  • parameter old_intent renamed to intent
  • parameter intent renamed to new_intent
  • parameter descriptionrenamed to new_description
  • parameter examples renamed to new_examples

updateEntity

  • parameter old_entity renamed to entity
  • parameter entity renamed to new_entity
  • parameter description renamed to new_description
  • parameter metadata renamed to new_metadata
  • parameter fuzzy_match renamed to new_fuzzy_match
  • parameter values renamed to new_values

updateValue

  • parameter old_value renamed to value
  • parameter value renamed to new value
  • parameter metadata renamed to new_metadata
  • parameter synonyms renamed to new_synonyms

updateSynonym

  • parameter old_synonym renamed to synonym
  • parameter synonym renamed to new_synonym

updateDialogNode

  • parameter old_dialog_node renamed to dialog_node
  • parameter dialog_node renamed to new_dialog_node
  • parameter description renamed to new_description
  • parameter conditions renamed to new_conditions
  • parameter parent renamed to new_parent
  • parameter previous_sibling renamed to new_previous_sibling
  • parameter output renamed to new_output
  • parameter context renamed to new_context
  • parameter metadata renamed to new_metadata
  • parameter next_step renamed to new_next_step
  • parameter title renamed to new_title
  • parameter type renamed to new_type
  • parameter event_name renamed to new_event_name
  • parameter variable renamed to new_variable
  • parameter actions renamed to new_action

updateCounterExample

  • parameter old_text renamed to text
  • parameter text renamed to new_text

Discovery

getEnvironments

  • getEnvironments method renamed to listEnvironments
  • parameter added name

getConfigurations

  • getConfigurations method renamed to listConfigurations
  • parameter added name

getCollectionFields

  • getCollectionFields method renamed to listCollectionFields

getCollections

  • getCollections method renamed to listCollections
  • parameter added name

createConfiguration

  • required parameter added name
  • parameter file removed
  • parameters added description, conversions, enrichments, normalizations

updateConfiguration

  • required parameter added name
  • parameter file removed
  • parameters added description, conversions, enrichments, normalizations

createCollection

  • parameter language_code renamed to language

updateCollection

  • parameter collection_name renamed to name
  • parameter language_code removed

addDocument

  • parameter metadata renamed to file_content_type

query

  • parameter collection_id changed to collection_ids which is a string array

Language Translator

getModels

  • getModels method renamed to listModels
  • parameter default renamed to default_models

getIdentifiableLanguages

  • getIdentifiableLanguages method renamed to listIdentifiableLanguages

Natural Language Classifier

create

  • create method renamed to createClassifier
  • required parameter added metadata

status

  • status method renamed to getClassifier

list

  • list method renamed to listClassifiers

remove

  • remove method renamed to deleteClassifier

Natural Language Understanding

analyze

  • parameter headers removed
  • optional parameters added clean, xpath, fallback_to_raw, return_analyzed_text, language, limit_text_characters

deleteModel

  • parameter headers removed

Personality Insights

profile

  • required parameters have changed from either text or content_items to content
  • required parameter added content_type

Text to Speech

Method Name Changes

  • synthesize renamed to postSynthesize
  • voice renamed to voicesByID
  • createCustomization renamed to postCustomizations
  • updateCustomization renamed to postCustomizationByID
  • getCustomization renamed to getCustomizationByID
  • deleteCustomization renamed to deleteCustomizationByID
  • addWords renamed to postCustomizationByIDWords
  • addWord renamed to putCustomizationByIDWord
  • getWords renamed to getCustomizationByIDWords
  • getWord renamed to getCustomizationByIDWord
  • deleteWord renamed to deleteCustomizationByIDWord

Tone Analyzer

tone_chat

  • tone_chat method renamed to toneChat

tone

  • required parameter added content_type
  • required parameter text renamed to tone_input

Speech to Text

createJob

  • createRecognitionJob method renamed to createJob

getRecognitionJobs

  • getRecognitionJobs method renamed to checkJobs

getRecognitionJob

  • getRecognitionJob method renamed to checkJob

deleteRecognitionJob

  • deleteRecognitionJob method renamed to deleteJob

createSession

  • parameters added customization_id, acoustic_customization_id, customization_weight

Visual Recognition

retrainClassifier

  • retrainClassifier method renamed to updateClassifier

recognizeText

  • method is no longer supported

classify

  • parameters url, classifier_ids, owners, and threshold encapsulated to new JSON object parameter parameters

detectFaces

  • parameter url encapsulated in JSON parameter parameters
Add a custom footer
Add a custom sidebar
Clone this wiki locally