Upload and restart SSEs

The Commerce REST APIs include endpoints you can use to upload and restart server-side extensions.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

Note: Before you upload a server-side extension to Commerce, be sure to remove any unneeded modules from the node_modules folder. You should include only the modules that the application requires. See Configure an SSE for more information.

Upload an SSE

To upload an extension to Commerce, you must first obtain an application key and use it to log into the Admin REST API. For example:

POST /ccadmin/v1/login  HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer <application_key>

grant_type=client_credentials

Commerce returns a bearer token, which you supply with subsequent requests.

Now use the POST /ccadmin/v1/serverExtensions endpoint to upload the extension:

POST /ccadmin/v1/serverExtensions  HTTP/1.1
Content-Type: multipart/form-data
Authorization: Bearer <access_token>

filename: <extension_name>.zip
uploadType: extensions
force: true
fileUpload: <open_handle_to_extension_file>

By default, when you upload an SSE, the extension server you upload it to restarts automatically. To track the progress of the restart, you can optionally set the trackProgress parameter to true in the body of the request. The response includes a workRequestId property that you can use in tracking requests. For example:

{
  "result": {
    "unzipped": false,
    "failedImages": 0,
    "allImagesFailed": false,
    "failedImagesReasons": {},
    "modifiedImages": 1,
    "newImages": 0,
    "assignedImages": 0
  },
  "success": true,
  "links": [
    {
      "rel": "self",
      "href": "/serverExtensions"
    }
  ],
  "token": "ff8eba3a8a2c_16fe",
  "message": "The extension has been uploaded. Please use the workRequestId to track the restart status.",
  "workRequestId": "mblNhrQ2D2"
}

You can then use the GET /ccadminx/custom/v1/servers/restartWorkRequestStatus endpoint to return information about the restart progress. This endpoint takes a workRequestId query parameter that you set to the value returned by POST /ccadmin/v1/serverExtensions. For example:

GET /ccadminx/custom/v1/servers/restartWorkRequestStatus?workRequestId=mblNhrQ2D2

The response is similar to this:

{
    "links": [
        {
            "rel": "self",
            "href": "http://myserver.example.com:7002/ccadminx/custom/v1/servers/restartWorkRequestStatus?workRequestId=e31212diwqjd"
        }
    ],
    "message": "SUCCEEDED",
    "workRequestId": "mblNhrQ2D2",
    "completionPercentage": 100
}

Manually restart SSEs

When you upload an SSE, you can optionally specify that the extension server should not restart automatically. This enables you to perform multiple uploads and then later separately trigger a restart for all your SSEs on the server.

To upload an SSE without restarting the server, set the restartExtensionServer property to false in the body of the POST /ccadmin/v1/serverExtensions endpoint request. By default, this property is true, so if you omit it from the request, the server will be restarted immediately after the upload.

To manually restart the server, use the POST /ccadminx/custom/v1/servers/restart endpoint. You can optionally include the trackProgress=true query parameter in the call to obtain a workRequestId value that you can then use to track the restart status:

POST /ccadminx/custom/v1/servers/restart?trackProgress=true  HTTP/1.1

The response includes the workRequestId. For example:

{
  "message": "The extension server restart request has been accepted. Please use the workRequestId to track the restart status.",
  "workRequestId": "mblNhrQ2D2",
  "links": [
  {
    "rel": "self",
    "href": "http://myserver.example.com:7002/ccadminx/custom/v1/servers/restart?trackProgress=true"
  }
  ]
}

You can then use the GET /ccadminx/custom/v1/servers/restartWorkRequestStatus endpoint to return information about the restart progress, as discussed above.

Delete SSEs

You can use the DELETE /ccadmin/v1/serverExtensions/<extension_name>.zip endpoint or the POST /ccadmin/v1/serverExtensions/deleteFiles endpoint to delete SSEs. When you delete SSEs, the extension server is restarted automatically by default. These endpoints can be called with the trackProgress=true query parameter to return a workRequestId value for passing to GET /ccadminx/custom/v1/servers/restartWorkRequestStatus.

These endpoints can also be called with the restartExtensionServer=false query parameter to delete SSEs without restarting the server. For example:

DELETE /ccadmin/v1/serverExtensions/test.zip?restartExtensionServer=false  HTTP/1.1