At the COExperience conference held May 13-16 in Dallas, TX, xLM Solutions and Senior PLM Solution Architect Ilan Madjar presented on the topic of 3DEXPERIENCE Public Restful APIs. This presentation was a hit with COExperience attendees. In this article, he provides further information to COE readers — whether they attended the session or are simply interested in the topic — sharing his responses to questions he commonly receives.
Q: What role do APIs play in overall 3DEXPERIENCE openness?
A: 3DEXPERIENCE provides a variety of tools and technologies to customize, integrate and migrate data as part of its openness. These include business logic (EKL language), widget framework and enterprise integration framework (EIF). The solution also supports various migration tools and methodologies, including EDAT and XPDM in on-premise implementations, migration assist for SW data, CAD connectors (PoweredBy), 3DXML and more.
The Rest API applies to the unified product structure (UPS) data model only and presents another layer of potential customization. The Rest Public API can be used to retrieve and author data from within the widget framework (custom widgets) in context of the EIF events, as well as from external applications (i.e., desktop applications such as .exe, java programs, etc., batch jobs, job server, etc.). The difference between the two is that external applications require 3DPassport authentication and the widget one does not.
Q: Where can I find API Documentation and how do I decipher this material?
A: The Documentation is available on 3ds.com. From the support menu, select Documentation, developer guides and cloud vs. on-premise options. When you reach the developer assistance section, the Rest API Documentation is under the “web services and events” section. The resource library names are intuitive. For example, 3DSpace will deal with all “PLM” (ENOVIA) data resources such as engineering items and CAD, while 3DSwym will deal with 3DSwym API for operations like “create wiki.” 3DPassport supports authentication to 3DPassport endpoints, etc.
The Documentation in some of the libraries such as the 3DSpace and distributed file store (FCS) is based on OpenAPI specifications, which can also be downloaded from the support site in JSON format. DS R&D has used Swagger to document the endpoint for these respective resources. Other resource libraries like 3DPassport and 3DSwym have a text-based description and do not use Open API spec. In both cases, however, the data model, theory and definition are described first and the actual HTTP command definitions for the end points are always at the end under the last bullet in the section (blue book icon).
Q: What skills are required to develop code using the 3DX APIs?
A: From a development perspective, you need basic web (client) development experience and skills as well as expertise in programming languages such as Java, JavaScript, C-Sharp, Python, etc. To have a complete skill set for developing 3DEXPERIENCE customizations, it’s also recommended for a developer to understand business logic and how 3DEXPERIENCE works with its various roles. If you are a traditional ENOVIA developer (mainly Java – JPO/JSP), you may want to brush up on your web development skills. Anyone programming in 3DX should have strong programming skills and understand 3DX web services and the business aspects and front-end user capabilities of the solution.
Q: Is there a specific IDE or language to use when developing 3DX customization with custom APIs?
A: No, there is not an exclusive IDE or programming language for developing 3DX customization with custom APIs. For the desktop/batch program (external), you can use any language that supports HTTP client requests and has a built-in resources/library (i.e., Intellij idea for Java, visual studio for .net, visual studio code for JavaScript or TypeScript or Python with Pycharm, and other various IDE). If you develop widgets or other web application clients, you would likely use JavaScript. At xLM we primarily use Visual Studio Code or Eclipse, but there are many options out there.
Q: Do you recommend any special tools or tips for developing using 3DX APIs?
A: I have found Swagger and Postman to be very useful tools for code generation. As previously stated when discussing Documentation, the 3DSpace resource library uses OpenAPI specifications. You can download the spec and use Swagger to generate code for some of the endpoints in whichever language you need (JavaScript, Java, etc.).
Postman, meanwhile, is useful for creating APIs and conducting unit testing of APIs. Postman supports code generation in various languages and is an effective tool for exchanging information with Dassault Systèmes Support regarding any issues with the API or the Documentation, if needed.
It’s important to note, however, that when working with Swagger and Postman for code generation, the code will be ad-hoc. You will still need to manage the wrapping logic (loops, recursion, etc.) and the cookies container, but the code generation will still be a time saver for new 3DEXPERIENCE Rest API developers. It will not generate 100% of the classes but will help by creating a starting point to work with. I recommend learning about Postman and OpenAPI/Swagger before trying them if you are new to the tools.
Q: What are some good ways to debug my customization when using 3DX API?
A: There are no special tips or tricks here. For external application development (i.e., executable desktop programs, add-ins, batch jobs, etc.) you can use the built-in IDE debug capabilities. It’s recommended to use IntelliJ Idea for Java and Visual Studio for .net development, etc., but I’ve personally found these tools aren’t necessarily intuitive or easy to navigate in certain situations.
I often prefer to use Fiddler as a proxy and trace the network HTTP traffic from the client. I find Fiddler to be a better tool for visually tracing request and response information. For widget development or other web application clients where JavaScript is used, you can use IDE to debug. Visual Studio code debugger has an extension for Node.js runtime and can debug JavaScript, TypeScript, etc. Any JavaScript debugging from web UI (i.e., widgets) can also make use of the browser debugger by pressing F12 in Chrome (depending on the browser type).
Q: What is the process for authenticating to the platform from an external application?
A: I encourage everyone to go through the extensive Documentation in the 3DPassport API library. It describes the process flow as well as the APIs (though mainly in Java examples — if you need support for other languages and have limited skills, please reach out to me). Generally, you do not need to authenticate if you are developing a custom widget (already authenticated) or if you are using the EIF roles (those use the good old basic HTTP authentication, but require the EIF licenses). You do need to authenticate for all other external application development needs.
- Get CAS Login Ticket (“CAS CSRserver CSRF token”) – ({{passport_url}}/login?action=get_auth_params)
- CAS Authenticate and redirect to a respective service (in this example 3DSpace) - {{passport_url}}/login?service={{3dspace_url_encoded}}
- Get respective service CSRF Token (in this example 3DSpace)
- {{space_url}}/resources/v1/application/CSRF
Check Documentation regarding cookies, payload and parameters. Once the service token is obtained, you can use the necessary resources endpoint to author data. Don’t forget to call the logout at the end {{passport_url}}/logout.
Ilan Madjar is a managing partner and senior architect at xLM Solutions, a SOLIDWORKS Certified Solutions Partner that specializes in PLM services and solutions. He brings 26 years of Product Lifecyle Management (PLM) experience to the process of solving customers’ challenges. Ilan is expert in developing and customizing enterprise solutions for xLM Solutions’ many clients and has widespread experience in PLM, PDM, CAD and other technology systems.