RepreZen API Studio supports declarative modeling of APIs and their underlying data structures using text notation as the primary editable syntax, with three supported API modeling languages. It also provides a live diagram view and generator, as a read-only graphical notation for APIs.
Supported API Modeling Languages
- OpenAPI 2.0, formerly know as the Swagger specification;
- OpenAPI 3.0, a new major revision of the OpenAPI industry standard; and
- RAPID-ML, RepreZen's domain-driven API modeling language.
These are text-based, declarative languages to describe REST APIs, and (in different ways), the data models that form the vocabulary of the REST API. RAPID-ML in particular emphasizes the data model as a format-independent domain model, a conceptual model of the business domain that you can adapt to individual APIs.
All three of these are modeling languages, using a textual syntax as the primary, editable form.
RepreZen API Studio also includes a live diagram view to show the resources, methods, request and response messages in a graphical presentation. In the case of RAPID-ML, the diagram also depicts resource-level data structures and hyperlinks. (If you'd like to see these diagram features supported for OpenAPI, please post to the feature requests forum!)
The diagram view is a read-only representation of the REST API (not the data model), with auto-layout, visibility controls, and a code generator that lets you publish the diagram in an interactive HTML page for your extended team and API client developers. The diagram view is not a graphical model editor, but with RAPID-ML, you can click the resource, data structure and method compartments to jump to the corresponding source declaration in the editor.
Text and Graphical Modeling Notations
We often think modeling and modeling language as terms that refer exclusively to graphical notations and graphical model editors. RepreZen API Studio and its supported languages don't fit into that definition of modeling. But they do:
- define a formal set of modeling constructs, or metamodel, formalizing the essential rules and semantics for concepts like resources, methods, and messages;
- support efficient, declarative representation of APIs and data models using text and/or graphical notations;
- capture the essential aspects at an appropriate level of abstraction; and,
- exclude other aspects or implementation details that would make the modeling environment less usable for its intended purpose, as a design tool.
These characteristics serve as a pretty good, general definition of what modeling means to us.