Contact Free trial Login

Creating an OData-Enabled API

The APIkit OData Extension supports OData (Open Data Protocol) to create HTTP-based data services.

The APIkit OData Extension builds the services from the entity data model (EDM), which OData services use to formalize their resource descriptions. You can write the EDM in RAML using EDM-compatible data types to represent API entities.

The APIkit OData extension generates Mule flows to manage OData requests. You can use the APIkit OData extension to, for example, expose a legacy API as an OData API, orchestrate data before exposing it in Salesforce, or create a bidirectional OData API for Oracle, DB2, or Azure DB.

The APIkit OData extension supports OData version 2.0.

The OData MySQL example on this page shows how to use an HTTP-based data service to query a MySQL database.

Prerequisites

The following software is required to create and use an OData REST API with APIkit:

  • OData Plugin

  • Mule EE 4.1.1 and later

  • Anypoint Studio 7.1.4 and later

Additionally, you must download the OData example entity data model.

Install the APIKit OData Extension

To install the APIKit OData extension in Anypoint Studio:

  1. Select Help > Install New Software.

  2. Click Add…​

    add update site
  3. In the Name field, type APIkit for ODATA Update Site.

  4. In the Location field, type http://studio.mulesoft.org/s4/apikit-for-odata/.

  5. Click Add.

    add repository odata
  6. Select the Anypoint ODATA Plugin box, and click Next.

    select odata extension
  7. Accept the terms and conditions of the product, then click Finish.

  8. Restart Studio to complete the installation.

Implement an API Using the APIkit OData Extension

The following example shows you how to implement an OData-enabled REST API:

  1. In Studio, select File > New > Mule Project.

  2. In the Project Name field, type the name of your Mule project.

  3. Click Finish.

  4. Copy the odata.raml file you downloaded in the prerequisites section to the /src/main/resources/api directory in your project.

  5. In the project explorer, right-click odata.raml and select Mule > Generate OData API from RAML Types.

    generate odata
  6. The OData extension generates the necessary files for your OData API implementation:

    list of odata files
    1 The Mule configuration file with the flows for the API implementation
    2 The generated RAML definition
    3 The generated RAML libraries
  7. Add the necessary logic for your API implementation in the flows.

OData MySQL Example

The OData MySQL example is a fully functional OData API packaged as a Maven project. In this example, the data source, the app, and the service are local.

First, you install a MySQL database and load tables using a provided script. Next, you import the compressed project into Studio, which includes a MySQL database driver. You can examine the flows to see how to implement the endpoints you need by accessing the data. Then you run the project and call the REST and OData services.

Install and Populate a MySQL Database

  1. Install a MySQL database and launch MySQL.

  2. Download the MySQL project example apikit-odata-example-master.jar.

  3. Run the example.sql script located in src/main/resources using MySQL commands to load data into a database named apikit-odata-example.

Implement the OData API

  1. In Studio, Select File > Import.

  2. Select Anypoint Studio > Packaged mule application (.jar) > Next.

  3. Browse for the apikit-odata-example-master.jar file and click Finish.

  4. In Studio, edit the mule-configuration.properties file inside the src/main/resources folder, and set the following properties to access the local MySQL database:

    ds.db.port=3306
    ds.db.user=<your MySQL user name>
    ds.db.host=<your MySQL host name>
    ds.db.database=apikit-odata-example
    ds.db.password=<your MySQL password>
  5. Run the API locally by right-clicking the project, and selecting Run As > Mule Application.

You can now access the REST and OData Service.

Access the REST and OData Service

To run the API locally:

  1. Right-click the project, and select Run As > Mule Application.

  2. Access the REST and OData Service using the following URLs:

    • REST API: /api

    • OData API: /api/odata.svc

      The following examples cover a few of the many REST calls and OData queries you can use.

Retrieve a List of Customers

Call the REST API to retrieve the list of customers:

http://localhost:8081/api/customers

The response is:

{
  "entries": [
    {
      "ContactName": "Maria Anders",
      "ContactTitle": "Sales Representative",
      "CompanyName": "Alfreds Futterkiste",
      "CustomerID": ""
    },
    {
      "ContactName": "Maria Anders",
      "ContactTitle": "Sales Representative",
      "CompanyName": "Alfreds Futterkiste",
      "CustomerID": "ALFKI"
    },
  ]
}

Access a Description of the OData Service

Get information about the collections behind this service:

http://localhost:8081/api/odata.svc

The response is:

<service xmlns="http://www.w3.org/2007/app" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:app="http://www.w3.org/2007/app" xml:base="http://localhost:8081">
  <workspace>
    <atom:title>Default</atom:title>
    <collection href="customers">
      <atom:title>customers</atom:title>
    </collection>
    <collection href="orders">
      <atom:title>orders</atom:title>
    </collection>
  </workspace>
</service>

Get OData Service Metadata

The Service Metadata exposes the structure of OData service resources, its operations, and EDM for a given service.

Get the metadata for HTTP Services:

http://localhost:8081/api/odata.svc/$metadata

The response aligns with the odata.raml EDM you used to build the HTTP Services API example:

<edmx:Edmx xmlns:edmx="http://schemas.microsoft.com/ado/2007/06/edmx" Version="1.0">
<edmx:DataServices xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" m:DataServiceVersion="2.0">
<Schema xmlns="http://schemas.microsoft.com/ado/2008/09/edm" Namespace="odata2.namespace">
<EntityType Name="customers">
<Key>
<PropertyRef Name="CustomerID"/>
</Key>
<Property Name="CompanyName" Type="Edm.String" Nullable="true" MaxLength="40" Unicode="false"/>
<Property Name="ContactName" Type="Edm.String" Nullable="true" MaxLength="30" Unicode="false"/>
<Property Name="ContactTitle" Type="Edm.String" Nullable="true" MaxLength="30" Unicode="false"/>
<Property Name="CustomerID" Type="Edm.String" Nullable="false" MaxLength="5" Unicode="false"/>
</EntityType>
<EntityType Name="orders">
<Key>
<PropertyRef Name="OrderID"/>
<PropertyRef Name="ShipName"/>
</Key>
<Property Name="Freight" Type="Edm.Decimal" Nullable="true" Precision="3" Scale="3" Unicode="false"/>
...

Query the Data Source

Issue OData queries to get the list of customers in XML and JSON format:

http://localhost:8081/api/odata.svc/customers
http://localhost:8081/api/odata.svc/customers?$format=json

Issue an OData query to get the tenth customer in the customer list:

http://localhost:8081/api/odata.svc/customers?$format=json&$top=1&$skip=10&$inlinecount=allpages

The response is:

{
    "d": {
        "results": [
            {
                "__metadata": {
                    "uri": "http:/localhost:8081/api/odata.svc/customers('BOTTM')",
                    "type": "odata2.namespace.customers"
                },
                "CompanyName": "Bottom-Dollar Markets",
                "ContactName": "Elizabeth Lincoln",
                "ContactTitle": "Accounting Manager",
                "CustomerID": "BOTTM"
            }
        ],
        "__count": "98"
    }
}

Was this article helpful?

💙 Thanks for your feedback!

Edit on GitHub