Using OData with RAML

<< Click to Display Table of Contents >>

Navigation:  Bizagi Studio > Bizagi from external applications > Bizagi API > OData RESTful services > Using Bizagi API in middlewares >

Using OData with RAML


Bizagi has a RESTful API to integrate external systems using the OData standard. Although OData itself is a standard, systems expect the specification of APIs in a single language. One of those languages is RAML. This modeling language provides a format that both the API provider and consumer can use.


There are service providers that use RAML to help organizations keep all their APIs centralized and organized. One API manager offering is Mulesoft. We will use Mulesoft to show how Bizagi OData services that can be used with RAML.


RAML descriptor of the OData layer

The integration layer of Bizagi is OData. The RAML descriptor translates the OData API in RAML, so you can create an asset in Anypoint, and use all the integration endpoints within Mulesoft.

This descriptor contains the following OData methods. See our Services index:













Before using the RAML Odata descriptor we recommend understanding the OData layer first. See getting started.


Download the Odata RAML descriptor

Click here to download the ZIP file containing the Bizagi Odata RAML descriptor.


Mulesoft structure

Integration between different systems is a common concern in organizations. The usual way to expose an integration layer is through APIs. Each system and application in core businesses may customize its API, based on technologies, protocols, and systems used. Managing and centralizing information related to APIs can be a demanding task that Mulesoft can make easier.


Within the same platform, you can upload systems APIs like Bizagi or Salesforce. Then create your API for specific business scenarios in a particular area, for example, Invoice payment in the Finance area. This business API can contain a whole set of systems APIs needed to execute business tasks like creating the customer invoice. Finally, you can create an experience layer of APIs aimed for devices or technologies, for example, a web application or a mobile device. The following picture shows how APIs can be structured in Mulesoft.




Mulesoft has a web-based platform named Anypoint, where you can manage the integration of all your systems and applications, by reusing their APIs.


Each API can be contained in one object called Asset. For each asset, you can define the documentation, policies, endpoints, and other information related to the API.


For asset creation, Anypoint has the Exchange module where you can add or create private or public assets. Mulesoft provides a public repository where you can expose public assets. You can also create private assets, and define their asset types, depending on how the API is exposed:







After creating or adding an asset, and configuring it, you can use the API related to the asset in applications that you can build in Anypoint.


Asset configuration

To configure the asset, you need to access the Anypoint platform.




Click the three-line menu at the top-left corner and select Exchange.




In your private master module, Click Publish new asset located at the top right corner.




Enter the asset name and select the REST API – RAML asset type. Then upload the ZIP file containing the Bizagi OData RAML descriptor. Make sure that the Main file is api.raml. Finally, click Publish.




When you access the asset, you see three main design areas:




1.Asset specification: This section contains the following items.





Bizagi OData methods contained in the RAML descriptor.


Description of the RAML file.


Types of responses that you can find throughout the endpoints. Each response object shows its JSON structure.


Authentication types which are available when you invoke each endpoint.

API instances

This section contains all the URLs from where you can invoke the API (asset).  From here, you can configure the URL of the Bizagi project that you are integrating through the Mulesoft asset.


2. The middle section is the design area. When you click a module from the left panel, Anypoint displays the design area of that object. For example, when you click an Endpoint, you find its description in the design area.




Here you find the description of each endpoint (OData method), including examples of inputs and outputs. For example, in POST methods, you can find the structure of the expected body input.




3. Details panel: In this panel, you find detailed information about the module you selected. You can also share the asset with other Mulseoft users, download the RAML descriptor, and add tags.




The tabs displayed in this panel depend on the module you selected in the asset specification section.


Learn how to set the asset with a Bizagi project.