The software basis for Shopware 6 is completely new and follows a rigorous API-first approach. The advantage of this compared to the previous version is that all functionalities of the new administration can also be managed via the API. By strictly following the API-first approach, three different API endpoints have emerged: Sync, SalesChannel and Admin. The Sync endpoint is designed for importing and exporting large amounts of data, whereby 300 products per second can currently be imported. Lengthy processes, such as creating thumbnails, are processed via a new messaging queue in the background.
Asynchronous processing accelerates the import process significantly, of course, and allows us to achieve a twenty-fold increase compared to Shopware 5. The Admin API is systematically used by the new administration, which is based on Vue.js. You can now use all the settings and functionalities that the admin offers via the API as well. This enables you to create custom interfaces for administrative tasks, such as a view for pending orders that need to be shipped. It doesn’t matter which technology is ultimately used for this purpose. Last but not least, there’s the SalesChannel API. This endpoint is responsible for all requirements for connecting your own shop frontend, POS or any other sales channels, enabling you to realise completely new sales concepts on the Internet. We have published various experiments on GitHub to show how simple it is to use the new API. These consist of a one-page shop, a shop snippet and an Alexa skill. The one-page shop is an experiment that shows how easy it is to build your own storefront for Shopware 6. The single page includes a functioning checkout with payment processing.
STAY TUNED!
Learn more about API Conference
The shop snippet is of interest to shop operators who blog a lot, work with influencers, etc. It allows you to integrate products from a Shopware 6 shop in a blog post with a simple snippet, for example. There’s also a link to the shop so you can buy there directly, of course. The third experiment, the Alexa skill, connects the Shopware 6 shop to Amazon’s Alexa. Once enabled, you can use Alexa voice commands to search for products, order them and have the product descriptions read aloud. Furthermore, the status of an order can be tracked and new products suggested. These experiments are a good introduction to using and understanding the SalesChannel API.
Now let’s have a look at the Admin API. In the following sections, we will set up a demo environment; create, update, delete a category; and see how to search for specific categories.
Setting up a Demo Environment
We use the Docker environment running on a Linux client. First, we clone the GitHub development template using git clone git@github.com:shopware/development.git. Now we have the development template for Shopware 6 in the development directory. We can now go into the directory using cd development and clone the actual Shopware platform repository into the standard directory using git clone git@github.com:shopware/platform.git. Caution: Please do not specify any other directory when cloning, as this is important for autoloading. We now have all the source code we need to get started on the computer. To build and start the necessary Docker containers, we enter ./psh.phar docker:start. We then connect to the application container via ./psh.phar docker:ssh and start the installation with ./psh.phar install.
This may take quite a while the first time, because the initial execution requires several caches to be created. To check whether the installation was successful, you can simply open your preferred browser and access http://localhost:8000. Mac users can also perform the set-up locally. You can find an example virtual host configuration in the Installation Guide under “Setting up your webserver”. All you have to do is execute bin/setup and you will be guided through an interactive installation process. If something doesn’t work during installation, check if there’s a file called .psh.yaml.override. If not, start the set-up script again with ./psh.phar install.
Using the Admin API
In the following examples, I use Guzzle 6. Other than that, I have no libraries in use. You can create the required client ID and client secret in the Administration by going to SETTINGS | SYSTEM | INTEGRATIONS and clicking ADD INTEGRATION. We can now use the client ID and client secret to generate a bearer token, which we will need for further API requests (Listing 1). Apart from OAuth, all other routes are versioned to ensure backward compatibility with future changes to the API. You can tell by the v1 in the route name. At the moment, only Version 1 exists. We now have all the necessary information in $token to authorise ourselves for the next requests. If we want to output all existing categories, we can do so as in Listing 2. Further examples on how to define filters, searches, sorting or limits for this query can be found in the online documentation for Shopware 6.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 | Listing 1: $client = new GuzzleHttp\Client([ 'base_uri' => 'http://localhost:8000', 'timeout' => 2.0, 'headers' => ['Content-Type' => 'application/json'],]);$token = $client->post( '/api/oauth/token', [ 'body' => json_encode([ 'client_id' => $clientId, 'client_secret' => $clientSecret, 'grant_type' => 'client_credentials', ]), ]); |
1 2 3 4 5 6 7 8 9 | Listing 2: $categories = $client->get( '/api/v1/category/', [ 'headers' => [ 'Authorization' => $token['token_type'] . ' ' . $token['access_token'], 'Accept' => 'application/json', ], ]); |
Top 3 API Design Sessions
So how do we set up a new category? Ultimately, much of what we do is identical to the request in which we retrieve all existing categories. The headers are identical and the endpoint in question is only extended by ?_response=true to receive a return from the API including the unique identifier generated. Furthermore, a POST request is issued instead of a GET request. In order to create a category named new category, we need the following source code snippet from Listing 3. We evaluate the return of the API in order to store the unique identifier of the category for further requests. To amend the newly created category, we don’t have to change much in the previous snippet. We replace ?_response=true with the unique identifier of the category and change the name to new category updated. The whole thing is then sent as a PATCH request. The snippet now in use can be found in Listing 4.
1 2 3 4 5 6 7 8 9 10 | Listing 3: $result = $client->post( '/api/v1/category?_response=true', [ 'headers' => [...], 'body' => json_encode(['name' => 'new Category']), ]);$result = json_decode((string) $result->getBody(), true);$categoryIdentifier = $result['data']['_uniqueIdentifier']; |
1 2 3 4 5 6 7 8 | Listing 4: $client->patch( '/api/v1/category/' . $categoryIdentifier, [ 'headers' => [...], 'body' => json_encode(['name' => 'new Category updated']), ]); |
Last but not least, we want to delete the newly created category from the system. You can find the corresponding source code snippet in Listing 5.
1 2 3 4 5 6 7 | Listing 5: $client->delete( '/api/v1/category/' . $categoryIdentifier, [ 'headers' => [...], ]); |
Conclusion
With its new API structure, Shopware offers shop operators, developers and agencies many new ways to establish their e-commerce presence. It has never been easier to connect third-party systems to Shopware, let alone build your own storefronts in order to enable an even greater customer-specific approach. Despite all the new functions, there is no negative impact on performance. The current benchmarks for the API are already rather promising and enable ERP integrations to implement new synchronisation concepts.
