April 9, 2018


API Studio Now Requires Java 8

API Studio 1.6 requires Java 8, and will require no longer run on Java 7.

Oracle ceased public availability of security fixes and upgrades for Java 7 in April 2015. Moving to Java 8 allows us to use new language features, and prepares API Studio for migration to newer versions of the Eclipse platform.

Please note that Java 9 will not be supported in this release, as it is incompatible with the Mars.2 Eclipse platform. We will migrating to a newer Eclipse platform version and adding Java 9 support in a later release of API Studio.

Please see the Java and Eclipse FAQ for further information.

Redesigned Custom Code Generation Framework

RepreZen API Studio has a powerful, extensible code generation framework that you can use to create your own generators. In API Studio 1.6, we have given the framework and tooling a major upgrade. Here are some of the new features and improvements:

  • OpenAPI 3.0 Support - You can now create OpenApi3 custom GenTemplates using the Xtend Generation Template project wizard. These use the open source KaiZen OpenAPI Parser, which provides a consistent, conformant Java object model for OAS v3.

  • Starter Code - We've brought the code generation framework, project wizard, and documentation up to date with our current best practices. The programming model is now more consistent across Swagger-OpenAPI v2, v3, and RAPID-ML. And the Xtend Generation Template project wizard produces starter code with extensive comments, so new developers can quickly understand how GenTemplates work.

  • Improved Xtend Editing - The default "Inkpot" color theme has better default mappings to the Xtend language. Background colors are now consistent, and template text now has a distinct red-orange color:

    Note: You might need to re-apply the Inkpot color theme or create a new workspace to see the improved color theme.

  • Documentation- Existing code generation docs have been updated, and we added a new Deep Dive that explains the GenTemplate Java APIs in full detail.

  • New "dynamic generators" are more flexible than output items, and should allow most developers to avoid creating their own implementations of the IGenTemplate.Generator interface.

  • GenTemplate.StaticGenerator - GenTemplate.Generator is deprecated; developers should use nearly equivalent GenTemplate.StaticGenerator, which is a static generator and so need not be tied directly to the GenTemplate -derived class.

  • Extract Types - We now support "extract" types for Swagger and OpenApi3 output items - in each case, the extractable types are those that appear in top-level (or component) maps.

New RAPID-ML Code Generators for Node.js and ASP.NET Core

There are two new RAPID-ML GenTemplates in this release:

  • Node.js Server - generates Node.js scaffolding for a service implementation directly from RAPID-ML. This follows the RAPID-Infuser pattern, generating a single type for each RAPID-ML data structure. Realization - including property sets, constraints, and reference treatments - are handled in the serialization/deserialization layer.

  • C# ASP.NET Core Server (Experimental) - A new experimental GenTemplate to create C# ASP.NET Core server stubs directly from RAPID-ML. 

Improved Realization of Multi-Valued References in RAPID-ML

RAPID-ML automatically links reference properties to resources bound to the referenced data structure. You can override this default behavior with explicit referenceLink or referenceEmbed statements.

With the new 1.6 release, explicit and automatic linking of multi-valued references is refined, to allow more flexible linking options:

  • A multi-valued reference linked to a collectionResource is realized as a single link. The target collection resource is expected to contain all referenced objects.

  • A multi-valued reference linked to an objectResource is realized as a collection of links. Each object is represented as a single link in the collection.

  • A multi-valued reference without an explicit referenceLink or referenceEmbed will be realized as a link to the default collectionResource bound to the referenced data structure. If there is no default collection resource, the multi-valued reference will be realized as a collection of links to the default objectResource. And if there is no default object resource, the reference will be realized as an embedded data structure.

Stricter Validations in RAPID-ML

There are certain syntax errors or logical errors that were tolerated by the RAPID-ML editor, but could result in unexpected output from code generators or documentation formats. These validations have been tightened in the 1.6 release.  In particular:

  • Use of the keyword this is now restricted to the syntax allowed according to the RAPID-ML language specification. It may only be used on a message with a resource-defined payload. Messages using this are always bound explicitly or implicitly to the containing resource.

  • An explicit referenceLink must always specify a targetResource. Reference links with an unspecified target resource were previously bound to a default target resource, but validation logic failed to detect cases where there was no target resource for the referenced data structure.

Other RAPID-ML Improvements and Bug Fixes

  • Improvements
    • Updated Swagger-OpenAPI generators to preserve the readOnly attribute of data structure properties. 
    • In the "Swagger (RAPID-XChange Contract)" GenTemplate, The _rapid_links property has been simplified, made readOnly, and renamed to _links. This generated property holds hyperlinks to resources related to a data structure. For backward compatibility, the Swagger GenTemplates support an optional linksPropertyName setting.
    • Improved support for reference cycles. Earlier releases of RAPID-ML forced cyclic references into a tree structure, with a depth limit. The new implementation preserves the original graph, with cycles. Code generation templates and live views have additional processing and presentation logic to detect and explicitly handle cycles correctly.
    • RAPID-ML documentation format now uses terminology consistent with the RAPID-ML language. The resource-level "Properties" heading is now "Resource Properties,"  and the data structure "Fields" heading is now "Data Properties."

  • Bug Fixes

    • Fixed WADL GenTemplate for RAPID-ML, so it uses an XML Schema GenTarget as a prerequisite.
    • Fixed JAX-RS generator for the "Enumerations" RAPID-ML example.
    • The readOnly and key attributes are now preserved correctly in inherited subtype properties.
    • Data structures imported from external RAPID-ML models now correctly include inherited properties.

Other General Improvements and Bug Fixes

  • Improvements
    • Warning-level markers in source models no longer prevent GenTargets from running. Only error-level markers should do this. 
    • Improved the default Inkpot color theme to make Git and Team views more readable.
  • Bug Fixes
    • Removed "Clean Generated" command from context menu, pending addition of UI confirmation and supporting preferences.