Migration of SMAPI from v0 to v1

Version 1 of the Skill Management API (SMAPI v1) allows the developer to obtain more information about a skill and its sub-resources, and to perform more specific operations. Version 1 is interoperable with Version 0, although the interfaces for the API calls have changed in many cases. Developers are encouraged to migrate to SMAPI v1 when possible. Refer to the SMAPI v1 documentation for each operation that you have used in your code in order to ensure that you make the appropriate updates.

The following changelog lists the differences between SMAPI v0 and SMAPI v1.

Name changes

The key skillManifest in requests/responses for v0 has been renamed to manifest in v1 requests/responses.

Changes to APIs

Skill Operations

SMAPI v1 supports development and live (case sensitive) as stage values for all GET operations that expect stage input. Otherwise, only development (case sensitive) is a supported value for stage. SMAPI v0 works with development stage implicitly, and therefore stage parameter is not used.

Create a Skill

v0: POST /v0/skills

v1: POST /v1/skills

Get a Skill Manifest

v0: GET /v0/skills/{skillId}

v1: GET /v1/skills/{skillId}/stages/{stage}/manifest

New error response:

HTTP/1.1 303 See Other when this API is called, and the skill creation process has not yet completed.

Update a Skill

v0: PUT /v0/skills/{skillId}

v1: PUT /v1/skills/{skillId}/stages/{stage}/manifest

New error responses:

HTTP/1.1 409 Conflict when an update is already is progress.

HTTP/1.1 403 Forbidden when the request cannot be fulfilled.

Get Skill Status

Version 1 returns manifest as well as interactionModel status. It also supports optional filtering by resource (interactionModel or manifest).

v0: /v0/skills/{skillId}/status

v1: /v1/skills/{skillId}/status?resource=name1&resource=name2

In the response, lastModified key has been renamed to lastUpdateRequest. The 'time' field is not returned in lastUpdateRequest. The error field in v0 has been replaced with errors in v1 which is now a list of error objects.

Account Linking

Get account linking partner

v0: GET /v0/skills/{skillId}/accountLinkingClient

v1: GET /v1/skills/{skillId}/stages/{stage}/accountLinkingClient

The AccountLinkingInformation in the response includes a new field, defaultTokenExpirationInSeconds, which indicates the number of seconds that the accessToken is valid. If the Oauth client returns "expires_in", it overwrites the defaultTokenExpirationInSeconds parameter.

The API returns HTTP/1.1 403 Forbidden when the request cannot be fulfilled.

Interaction model building status

SMAPI v1 does not provide dedicated api to get interaction model building status. However, it can be retrieved using 'get skill status' api. See Get skill status

v1 API doesn't take locale as input and therefore returns status for all available locales in response. The status value in case the last interaction model was built successfully, has been renamed from SUCCESS in v0 to SUCCEEDED in v1.