As you might have read in our Product Release Notes for August 2024, we have completed a major step towards significantly improving the experience in consuming our HTTP APIs.
Here is what happened:
The implementation of our public facing APIs is now aligned with the API specification and will stay that way. All of the endpoints now use the models generated from the specifications.
We segregated input and response models, making it more transparent in which case which fields are required/supported, thus saving API consumers some amount of business/validation logic on their end and reduce room for misunderstandings.
Validation has been improved and made more strict to reduce the amount of potential errors when making requests.
The OpenAPI specification can now be downloaded and used for code generation on the consumer side.
Going forward, the latest API specifcations will be made available in API Documentation . You might see a little (non-breaking) churn, as we iron out the last kinks. Make sure to check in from time to time.
If you spot something that is off, please to not hesitate to reach out in the forum and we’ll be on it.
You kept on speaking, and we didn’t stop listening. @s.wuerth nudged us to finally push out changelogs for API changes.You might already have noticed it, depending on which private API categories you have access to.
If you haven’t: We’re generating changelogs for each API change automagically now on each release.
For stable APIs, we still make non-breaking changes that will be described in the logs.
Beta APIs might be subject to breaking changes, too. We’ll dig deeper into our currently evolving versioning strategy soon.
Don’t worry if they are still empty - not all of the APIs have seen changes recently. But you can already subscribe to the logs relevant for you and stay in the know.
Here's a contrived example of how they (will) look like
POST /systems
removed the required property ‘createdAt’ from the response with the ‘201’ status
removed the optional property ‘productOptionUpdatedAt’ from the response with the ‘201’ status
added the optional property ‘productOptionUpdatedAtFoo’ to the response with the ‘201’ status
GET /systems/{systemID}
removed the required property ‘createdAt’ from the response with the ‘200’ status
removed the optional property ‘productOptionUpdatedAt’ from the response with the ‘200’ status
added the optional property ‘productOptionUpdatedAtFoo’ to the response with the ‘200’ status
PATCH /systems/{systemID}
removed the required property ‘createdAt’ from the response with the ‘200’ status
removed the optional property ‘productOptionUpdatedAt’ from the response with the ‘200’ status
added the optional property ‘productOptionUpdatedAtFoo’ to the response with the ‘200’ status
You can use the information from the changelogs to quickly see new features or updates in the APIs as they become available and see whether you can optimize your API usage based on that. As always: If you notice any odd behavior, let us know!
And if you’re curious how we built this: We use oasdiff wrapped into a GitHub action and another one to post the result to the forum. Similar to what we did with the specs and snippets as described . It’s evolved into a nice toolchain, and we’ll probably write it down in detail somewhere. Would you be interested? Let us know!
Based on your valuable feedback , we have prepared a few more updates to the API documentations hosted here.
Auth Token Persistence: The authentication token you enter in the Authorization section is now persisted in you browser’s local storage. This has two implications. Firstly, you should not enter tokens on shared computers. But then, when using shared machines, you’re probably using private browsing windows anyway. Secondly, you don’t have to enter your token over and over again. In combination with using token authorization, this saves you some effort.
Improved Search: Instead of only using a simple filter, you can now search within paths, parameters etc. specifically.
Fixed Sidebar Navigation: Previously, the API documentation navigation was hidden on smaller screen sizes, which was confusing. This does not happen anymore now.
Always show schema property descriptions fully: Previously, descriptions of fields in request and response schemas were collapsed if they had more than one line. We now expand the full description by default. You can still toggle between both variants depending on your preference.
aligned with the API specification and will stay that way. All of the endpoints now use the models generated from the specifications.
: We made it available under the MIT licence 
removed the required property ‘createdAt’ from the response with the ‘201’ status
. It’s evolved into a nice toolchain, and we’ll probably write it down in detail somewhere. Would you be interested? Let us know!
, we have prepared a few more updates to the API documentations hosted here.
