Contact Us 1-800-596-4880
  1. Homepage
  2. APIkit (4.x)
  3. APIkit for OData V2

  4. Module Reference

APIkit for OData v2 Module Reference

Learn about dependency, namespace, and schema information in APIkit for OData v2 to collaborate, build applications, and maintain codebases.

Dependency Information

Declare the APIkit for OData v2 extension with the APIkit for REST module dependency:

<dependency>
    <groupId>org.mule.modules</groupId>
    <artifactId>mule-module-apikit-odata</artifactId>
    <version>2.2.0</version> (1)
    <classifier>mule-plugin</classifier>
</dependency>
<dependency>
    <groupId>org.mule.modules</groupId>
    <artifactId>mule-apikit-module</artifactId>
    <version>1.8.3</version> (1)
    <classifier>mule-plugin</classifier>
</dependency>
1 The tooling determines the appropriate version of each dependency when scaffolding to guarantee compatibility. Manually setting dependency versions produces issues. See the APIkit release notes before upgrading each component to the latest version.
Update the Anypoint Studio plugin to enable the tooling to determine the appropriate dependency combination.

Namespace and Schema

xmlns:apikit="http://www.mulesoft.org/schema/mule/mule-apikit"
xsi:schemaLocation="http://www.mulesoft.org/schema/mule/mule-apikit http://www.mulesoft.org/schema/mule/mule-apikit/current/mule-apikit.xsd"

Customizing EntitySet Names

APIkit for OData v2 pluralizes entity type names automatically to create EntitySet endpoints (for example, Person becomes Persons). For APIkit for OData 2.3.5 and later, override this behavior by using these annotations in your RAML type definitions:

  • (odata.entitySet)

  • (odata.entitySetEnabled)

With these annotations, you control the EntitySet name exposed in metadata and in OData API URLs and align endpoints with your domain (for example, change Person to People).

Annotation Reference

Apply these annotations at the entity type level in your RAML library (for example, in odataLibrary.raml):

Annotation Type Description

(odata.entitySet)

String

Custom name for the entity set. Used only if (odata.entitySetEnabled) is true and the value is non-empty.

(odata.entitySetEnabled)

Boolean

If true, uses the custom name from (odata.entitySet). If false or omitted, default pluralization is used for backward compatibility.

Feature Flag: Enabling Custom EntitySet Names

The (odata.entitySet) and (odata.entitySetEnabled) entity annotations affect metadata generation and OData API behavior as follows:

Case (odata.entitySetEnabled) (odata.entitySet) Effective EntitySet Name Metadata and OData API Behavior

1

false

Present

Default pluralization (based on entity type)

Default EntitySet

2

false

Not present

Default pluralization (based on entity type)

Default EntitySet

3

Not defined or present

Present

Default pluralization (based on entity type)

Default EntitySet

4

Not defined or present

Not present

Default pluralization (based on entity type)

Default EntitySet

5

true

Present (non-empty)

Custom name from annotation

Custom EntitySet; metadata and APIs use the custom name

6

true

Not present or empty

Default pluralization (based on entity type)

Default EntitySet
Custom names apply if entitySetEnabled is true and entitySet is provided with a non-empty value. If not, APIkit for OData v2 uses default pluralization.

Example: Custom EntitySet Name in RAML

This example defines a Person entity and exposes it as the EntitySet People:

#%RAML 1.0 Library
uses:
  odata: libraries/odataLibrary.raml

types:
  Person:
    (odata.remote): Person
    (odata.entitySet): People
    (odata.entitySetEnabled): true
    properties:
      ID:
        type: integer
        required: true
        (odata.key): true
      Name:
        type: string
        required: true
      Price:
        type: number

The EntitySet appears as People in $metadata and in OData API URLs (for example, /api/odata.svc/People) instead of the default Persons.

Backward Compatibility

Existing flows and APIs don’t change unless you explicitly enable the feature. APIkit for OData v2 ignores custom EntitySet annotations unless (odata.entitySetEnabled) is set to true. If the flag is false or missing, APIkit for OData v2 always uses default pluralization based on the entity type, even if (odata.entitySet) is present. This ensures full backward compatibility with existing APIkit for OData v2 applications.

See Also