Upgrade Guide Werk24 Client V1 -> V2
Motivation
Version 1 of the API, originally developed in 2019, evolved incrementally over time. New features were added, while others were deprecated, leading to technical debt and increased complexity. This made maintenance challenging and introduced confusion for new developers. Over the years, we also gained a deeper understanding of mechanical engineering concepts and improved our approach to handling complexities. These insights have shaped the development of Version 2, making it more streamlined and efficient.
What has changed?
1. Simplified Requests
The API now consolidates requests into four main categories:
- AskMetadata – Replaces the old W24AskTitleBlock.
- AskFeatures – Merges multiple previous requests, including W24AskVariantRoughnesses, W24AskVariantRadii, W24AskVariantMeasures, and W24AskVariantGDTs.
- AskInsights – Incorporates data from W24AskVariantExternalDimensions and AskVariantProcesses.
- AskRedaction – A new request type that allows for redaction proposals, replacing W24SheetRebranding and W24SheetAnonymization while enabling pre-redaction modifications.
2. Clearer API Output
Previously, API responses could be overwhelming, with excessive details like balloon (annotation) positions cluttering the output. To address this, we've introduced an auxiliary request called AskBalloon. If you require balloon-related data, you can request it separately. Otherwise, responses are now more focused and concise.
3. Simplified Client
To improve clarity and usability, the client has been renamed from W24Client to Werk24Client.
4. Enhanced CLI
The Command Line Interface (CLI) has been completely redesigned with new features. Notably, you can now generate a trial license directly and start using the API without prior contact.
Do I need to upgrade?
Yes, but you have some flexibility. The old API remains supported for now, allowing continued use. However, to take advantage of the new features, upgrading is recommended. Additionally, we will actively monitor usage and remove deprecated Ask types from the API after 90 days of inactivity.
How do I upgrade
1. Update your Ask Types
Refer to the table below for the required changes:
| Old Ask | New Ask |
|---|---|
| W24AskCanvasThumbnail | - |
| W24AskNotes | AskMetaData |
| W24AskPageThumbnail | AskSheetImages |
| W24AskPartFamilyCharacterization | AskCustom |
| W24AskProductPMIExtract | AskMetaData and AskFeatures |
| W24AskRevisionTable | - |
| W24AskSectionalThumbnail | AskViewImages |
| W24AskSheetAnonymization | AskRedaction |
| W24AskSheetRebranding | AskRedaction |
| W24AskSheetThumbnail | AskSheetImages |
| W24AskTitleBlock | AskMetaData |
| W24AskTrain | - |
| W24AskVariantExternalDimensions | AskInsights |
| W24AskVariantCAD | - |
| W24AskVariantGDTs | AskFeatures |
| W24AskVariantMeasures | AskFeatures |
| W24AskVariantRadii | AskFeatures |
| W24AskVariantRoughnesses | AskFeatures |
| W24AskVariantProcesses | AskInsights |
2. Update your Client and imports
- The old client (W24Client) has been replaced by Werk24Client.
- All models can now be imported directly from the werk24 package for greater simplicity.
3. Update your Response handling
- Responses are no longer dictionaries; they are now Pydantic models.
- To convert responses to JSON, use the model_dump() function
By following these steps, you can smoothly transition to Version 2 and leverage the improved functionality of the Werk24 API.