Access Configured Commerce API reference
Optimizely Configured Commerce exposes its REST APIs through a Swagger user interface. Swagger is an interactive reference that lets you browse available endpoints, view request and response models, and send test requests from the browser.
Use this article to find the correct Swagger URL for your environment and .NET version. Configured Commerce runs on two .NET versions, and the Swagger paths differ between them. This article covers hosted sandbox access and local instance access.
Before you begin
Confirm the following before you try to open the Swagger reference:
- You know which .NET version your instance runs: .NET Framework 4.8 or .NET Core.
- On .NET Core, you know which group of APIs you need: admin, storefront, or integration.
- For a hosted reference, you have the URL of your sandbox site.
- For a local reference, your Configured Commerce application is running on your machine.
Swagger is available on sandbox sites only. It is not exposed on production sites.
Swagger URLs by environment
The following table lists the Swagger user interface paths for each environment and .NET version. Replace SANDBOX_SITE with the host name of your sandbox site, and replace PORT with the port your local application uses.
Environment | .NET version | Swagger user interface URL |
|---|---|---|
Hosted sandbox | .NET Framework 4.8 | https://SANDBOX_SITE/swagger/ui/index |
Hosted sandbox | .NET Core | https://SANDBOX_SITE/admin/swagger https://SANDBOX_SITE/storefront/swagger https://SANDBOX_SITE/integration/swagger |
Local instance | .NET Framework 4.8 | http://localhost:PORT/swagger/ui/index |
Local instance | .NET Core | http://localhost:30100/admin/swagger http://localhost:30100/storefront/swagger http://localhost:30100/integration/swagger |
On .NET Framework 4.8, /swagger redirects to /swagger/ui/index, so either path opens the same reference.
In .NET Core, the Configured Commerce APIs are split across three Swagger references, one for each application: Admin, Storefront, and Integration. Each reference lists only the APIs in its group, so open the one that matches the APIs you need. The .NET Framework 4.8 path lists the APIs in a single reference that has a document selector.
Access the hosted Swagger reference
Follow these steps to open the Swagger reference on a sandbox site:
- Confirm the .NET version of your sandbox instance.
- Copy the matching URL from the Access Configured Commerce API reference. On .NET Core, choose the path for the API group you need.
- Replace SANDBOX_SITE with your sandbox host name.
- Open the URL in a browser.
The Swagger reference lists the Configured Commerce APIs available on that site. Requests you send from the reference run against the same sandbox host.
On .NET Core, the Admin, Storefront, and Integration APIs run as three separate applications, but a reverse proxy routes the /admin, /storefront, and /integration paths to the matching application. All three Swagger references are therefore available under your single sandbox host name.
Access the local Swagger reference
If you run Configured Commerce on your own machine, Swagger is served from the local application. Follow these steps to open it:
- Start the Configured Commerce application on your machine.
- Note the port the application uses.
- Open the matching local URL from the Swagger URLs by environment table in a browser.
If the page does not load, confirm that the application is running and that no other process uses the same port.
Local .NET Core ports
The local .NET Core environment runs the three applications behind a reverse proxy. Open the Swagger references through the proxy port, which is 30100 by default, in the same way you would on a sandbox site.
You can also reach each Swagger reference directly on the port of its own application. The following table lists the default direct ports:
Application | Default port | Direct Swagger user interface URL |
|---|---|---|
Storefront API | 30040 | http://localhost:30040/storefront/swagger |
Admin API | 30070 | http://localhost:30070/admin/swagger |
Integration API | 30080 | http://localhost:30080/integration/swagger |
The path prefix stays the same on the direct port, because each application serves its Swagger reference under its own prefix.
If you changed the port values in your local environment configuration, use your own values instead of the defaults.
.NET version differences
Configured Commerce supports two .NET versions, and the Swagger routes differ between them:
- In .NET Framework 4.8, all APIs appear in one reference at /swagger/ui/index. This path does not change. The reference has a document selector that lists Storefront API V1, Storefront API V2, and Admin API V1. There is no integration document on .NET Framework 4.8.
- In .NET Core, the APIs are split into three references, at /admin/swagger, /storefront/swagger, and /integration/swagger. The storefront reference has a document selector for storefront V1 and V2. The admin and integration references each contain a single document.
Confirm your .NET version before you select a URL, because the paths are not interchangeable.
Troubleshoot Swagger access
The following table lists common issues and how to resolve them:
Issue | Cause | Resolution |
|---|---|---|
The Swagger page returns an error on a production site | Swagger is not exposed on production | Use a sandbox site instead |
The local Swagger page does not load | The application is not running | Start the application and reload the page |
The local Swagger page does not load on the expected port | Another process is using the port | Stop the conflicting process, or start the application on a different port and use that port in the URL |
A .NET Core path returns an error | The instance runs .NET Framework 4.8 | Confirm the .NET version and use the /swagger/ui/index path |
A .NET Core path loads but does not list the API you need | You opened the reference for a different API group | Open the admin, storefront, or integration reference that matches the API you need |
A local .NET Core path returns an error on a direct port | You used the port of a different application | Use the reverse proxy port, or the direct port that matches the path prefix |