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 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
For more details about each API, see Skill Manifest REST API Reference.
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 the 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.
See Get skill status.
Delete a skill
-
v0: DELETE /v0/skills/{skillId}/
-
v1: DELETE /v1/skills/{skillId}/
New error responses:
Instead of HTTP/1.1 400 Bad Request
as in v0, SMAPI v1 returns HTTP/1.1 403 Forbidden
when there is a live
stage, or if the skill is in certification, or if model building is in progress.
List skills
Version 1 optionally allows the developer to retrieve listings for specified skill(s) under a specific vendorId
, rather than skills page by page under that vendorId
.
-
v0: GET /v0/skills?vendorId={vendorId}&maxResults={num}&nextToken={token}
-
v1: GET /v1/skills?vendorId={vendorId}&maxResults={num}&nextToken={token} OR GET /v1/skills?vendorId={vendorId}&skillId={skillId1}&skillId={skillId2}
Additional skill information fields (apis
and publicationStatus
) are included in the response.
Account Linking
The Account Linking Operations APIs now accept stage as a parameter. For details, see Account Linking Management.
The accountLinkingRequest
structure now contains redirectUrls
as a possible field. For details, see Account Linking Request.
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.
Set account linking partner
-
v0: PUT /v0/skills/{skillId}/accountLinkingClient
-
v1: PUT /v1/skills/{skillId}/stages/{stage}/accountLinkingClient
Version 1 throws HTTP/1.1 403 Forbidden
when the skill is in certification, whereas v0 throws HTTP/1.1 400 Bad Request
.
Delete account linking partner
New to v1.
- v1: DELETE /v1/skills/{skillId}/stages/{stage}/accountLinkingClient
Skill enablement operations
This set of APIs, which allows you to programmatically manage skill enablements rather than rely on the developer console, is new to v1. See Skill Enablement Operations.
Interaction Model Operations
The Interaction Model Operations APIs now accept stage
as a parameter. For details, see Interaction Model Management.
Get interaction model
-
v0: GET /v0/skills/{skillId}/interactionModel/locales/{locale}
-
v1: GET /v1/skills/{skillId}/stages/{stage}/interactionModel/locales/{locale}
Head interaction model
-
v0: HEAD /v0/skills/{skillId}/interactionModel/locales/{locale}
-
v1: HEAD /v1/skills/{skillId}/stages/{stage}/interactionModel/locales/{locale}
The successful status codes have changed as follows:
-
v0:
HTTP/1.1 200 OK
-
v1:
HTTP/1.1 204 No Content
Update an interaction model
The verb for updating an interaction model has changed.
-
v0: POST /v0/skills/{skillId}/interactionModel/locales/{locale}
-
v1: PUT /v1/skills/{skillId}/stages/{stage}/interactionModel/locales/{locale}
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.
-
v0: GET /v0/skills/{skillId}/interactionModel/locales/{locale}/status
-
v1: GET /v1/skills/{skillId}/status?resource=interactionModel
Skill Certification Operations
The error responses have changed from HTTP/1.1 400 Bad Request
to HTTP/1.1 403 Forbidden
. For details, see Skill Certification Operations.
Submit skill for certification
v0: POST /v0/skills/{skillId}/submit
v1: POST /v1/skills/{skillId}/submit
Withdraw skill from certification
v0: POST /v0/skills/{skillId}/withdraw
v1: POST /v1/skills/{skillId}/withdraw
ASK CLI Changes
All of the SMAPI v1 changes described on this page have corresponding changes in the ASK CLI Command Reference.
Last updated: Apr 30, 2024