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!
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!