Contact Us 1-800-596-4880
  1. Homepage
  2. APIkit
  3. APIkit for OData V4

  4. Building, Implementing, and Testing an API

Building, Implementing, and Testing an OData V4 API

You can query a MySQL database with the OData MySQL example by using an HTTP-based data service.

Before You Begin

You must install the following software to create and use an OData REST API with APIkit:

  • OData Plugin

  • Mule runtime engine 4.3.0 or later

  • Anypoint Studio 7.9.0 or later

Additionally, you must download the OData 4 implementation example.

Scaffold an OData V4 API Using APIkit for OData

  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. In src/main/resources/api, create a new file with a .csdl.xml extension.

    For example, odata-metadata.csdl.xml:

    1 EntityType defines the type and its properties.
    2 key defines which property or set of properties is the key for the entity.

    For example, the entity set Orders comprises two keys: OrderID and ShipName.
    3 EntityContainer defines the sets of exposed entities.

    In this example, Orders and Customers.
    4 EntitySet contains a name and EntityType.

    You must define them in the schema namespace.

  5. In the Package Explorer, right-click your odata-metadata.csdl.xml file and select Generate Mule OData 4 API:

    The path to the Generate Mule OData 4 API option highlighted

  6. APIkit generates the corresponding flows based on your .csdl.xml metadata file.

    The three flows created from the `csdl.xml` metadata file are highlighted.
    1 The main flow receives messages and routes the operation to the correct handler.
    2 Five flows with GET, PUT, POST, and DELETE operations for each entity.
    3 A flow with a GET operation to retrieve the collection of entities.

Handle OData System Query Options

Within each On Entity Request and On Entity Collection Request listener you can access a systemQueryOptions attribute that maps to each OData query option ($select, $orderby, $count, etc.). For example, to access the $select value you use the following expression:

#[attributes.odataRequestAttributes.systemQueryOptions.select]
odataRequestAttributes highlighted in the output tab, within the Mule message, under attributes

APIkit for OData 4 Implementation Example

  1. Download the full apikit-odata4-example.

  2. Import the downloaded example in Studio.

  3. Run the SQL statements in the src/main/resources/example.sql file to create the database, tables, and test data in MySQL database.

  4. Run the application in Studio.

After Studio deploys the application, you can query your OData service using the following query examples:

GET Request Example

Request
curl --location --request GET 'localhost:8081/api/Customers('BLAUS')'
curl
Response
{
  "@odata.context": "http://localhost:8081/api/$metadata#Customers/$entity",
  "CompanyName": "Blauer See Delikatessen",
  "ContactName": "Hanna Moos",
  "ContactTitle": "Sales Representative",
  "CustomerID": "BLAUS"
}
JSON

GET Request Example With Composite Key

Request
curl --location --request GET 'localhost:8081/api/Orders(OrderID=10315,ShipName='Island Trading')
curl
Response
{
  "@odata.context": "http://localhost:8081/api/$metadata#Orders/$entity",
  "Freight": 41.76,
  "OrderDate": "1996-09-26T00:00:00Z",
  "OrderID": "10315",
  "Price": null,
  "Priority": 1,
  "ShipAddress": "Garden house Crowther Way",
  "ShipName": "Island Trading"
}
JSON

Create Example

In this example, the client provides the key (or keys) to create a new entity:

POST Customer Request
curl --location --request POST 'http://localhost:8081/api/Customers' \
--header 'Content-Type: application/json' \
--data-raw '{
   "CompanyName": "Mulesoft",
   "ContactName": "Customer 123",
   "CustomerID": "NW123"
}'
curl
POST Order
curl --location --request POST 'http://localhost:8081/api/Orders' \
--header 'Content-Type: application/json' \
--data-raw '{
   "Freight": 32.38,
   "OrderID": 100000,
   "ShipAddress": "Unknown St. 123",
   "ShipName": "Order 100000"
}'
curl

Update Example

OData V4 recommends using PATCH to update entities because it only changes the provided fields:

PATCH
curl --location --request PATCH 'http://localhost:8081/api/Customers('\''BOTTM'\'')' \
--header 'Content-Type: application/json' \
--data-raw '{
   "ContactName": "James Bottom"
}'
curl
curl --location --request PATCH 'http://localhost:8081/api/Orders(OrderID=10251,ShipName='\''Victuailles en stock'\'')' \
--header 'Content-Type: application/json' \
--data-raw '{
   "ShipAddress": "Unknown Av. 1234"
}'
curl

OData V4 discourages the usage of PUT to update your entities because PUT replaces the entire entity with the new one, which can lead to data loss.

PUT
curl --location --request PUT 'http://localhost:8081/api/Customers('\''LONEP'\'')' \
--header 'Content-Type: application/json' \
--data-raw '{
   "CompanyName": "New Lonesome Pine Restaurant",
   "ContactName": "Fran C. Wilson",
   "CustomerID": "LONEP"
}'
curl
curl --location --request PUT 'http://localhost:8081/api/Orders(OrderID=11056,ShipName='\''Eastern Connection'\'')' \
--header 'Content-Type: application/json' \
--data-raw '{
   "Freight": 27.52,
   "OrderDate": "1998-05-28T00:00:00",
   "OrderID": 11056,
   "Priority": 2,
   "ShipAddress": "45 King George",
   "ShipName": "Eastern Connection"
}'
curl

Delete Example

To delete the entity:

DELETE
curl --location --request DELETE 'http://localhost:8081/api/Customers('\''NW123'\'')'
curl
curl --location --request DELETE 'http://localhost:8081/api/Orders(OrderID=11056,ShipName='\''Eastern Connection'\'')'
curl

Client-Side Pagination in APIkit for OData 4

You can configure your client to request the page using the HTTP query parameters $skip and $top.

  • The $top system query parameter specifies a non-negative integer n that limits the number of items returned from a collection.

  • The $skip system query parameter specifies a non-negative integer n that excludes the first n items of the queried collection from the result.

For example:

curl -X GET ‘localhost:8081/api/Customers?$skip=1&$top=5’
curl

Returns five records starting from the second position.

Server-Side Pagination in APIkit for OData 4

Server-side pagination enables you to control a subset of data requests fetched from a client-side server by using a fixed pageSize parameter. It divides the response data set into discrete pages to improve data readability. The server defines the page size, which is the maximum number of records that the server returns in a request.

Server-Side Pagination Operation in OData 4

OData defines a @odata.nextLink to indicate that a response is only a subset of the requested collection of entities. As such, @odata.nextLink contains a URL that enables the client to retrieve the next subset of the requested collection. The URL contains a query parameter $skiptoken that indicates the server where the next page starts.

Implement Server-Side Pagination in APIkit for OData 4

You can implement the server-side pagination by defining a set of fields with <apikit-odata:request-entity-collection-listener> in the Responses tab in Anypoint Studio.

pageSize set to ${service.orders.pageSize} in the On Entity Collection Request tab

After pageSize is populated, APIkit creates the XML representation of the previous fields:

<apikit-odata:request-entity-collection-listener config-ref="odata-metadata-config" path="/Orders" method="GET" >
        <apikit-odata:collection-success-response >
            <apikit-odata:entity-collection-success-response pageSize="${service.orders.pageSize}"/>
        </apikit-odata:collection-success-response>
    <apikit-odata:request-entity-collection-listener>
xml

Page Size or Token Fields for Server-Side Pagination

Page size is a fixed number that represents the maximum number of records the request-entity-collection listener can retrieve for each request. In case you cannot use a numeric pagination, set a token in the Token field, so a developer can generate it in the corresponding flow. APIkit for OData includes this token value in the @odata.nextLink URL with a query parameter $skiptoken=<Token_Value>.

See Also