Import SAP OData metadata as an API

APPLIES TO: All API Management tiers

This article shows how to import an OData service using its metadata description. In this article, SAP Gateway Foundation serves as an example.

In this article, you'll:

• Retrieve OData metadata from your SAP service
• Import OData metadata to API Management, either directly or after conversion to an OpenAPI specification
• Complete API configuration
• Test the API in the Azure portal

Note

Importing an OData API to API Management from its metadata description is in preview. Learn more.

Prerequisites

• An existing API Management instance. Create one if you haven't already.

• An SAP system and service exposed as OData v2 or v4.

• If your SAP backend uses a self-signed certificate (for test purposes), you may need to disable the verification of the trust chain for SSL. To do so, configure a backend in your API Management instance:

  1. In the Azure portal, under APIs, select Backends > + Add.
  2. Add a Custom URL pointing to the SAP backend service.
  3. Uncheck Validate certificate chain and Validate certificate name.

  Note

  For production scenarios, use proper certificates for end-to-end SSL verification.

Retrieve OData metadata from your SAP service

Retrieve metadata XML from your SAP service, using one of the following methods. If you plan to convert the metadata XML to an OpenAPI specification, save the file locally.

• Use the SAP Gateway Client (transaction /IWFND/GW_CLIENT), or
• Make a direct HTTP call to retrieve the XML: http://<OData server URL>:<port>/<path>/$metadata

Go to your API Management instance

1. In the Azure portal, search for and select API Management services.

   

2. On the API Management services page, select your API Management instance.

   

Import API to API Management

Choose one of the following methods to import your API to API Management: import the metadata XML as an OData API directly, or convert the metadata XML to an OpenAPI specification.

OData metadata

Import OData metadata

1. In the left menu, select APIs > + Add API.

2. Under Create from definition, select OData.

   

3. Enter API settings. You can update your settings later by going to the Settings tab of the API.

   1. In OData specification, enter a URL for an OData metadata endpoint, typically the URL to the service root, appended with /$metadata. Alternatively, select a local OData XML file to import.

   2. Enter remaining settings to configure your API. These settings are explained in the Import and publish your first API tutorial.

4. Select Create.

   The API is added to the APIs list. The entity sets and functions that are exposed in the OData metadata description appear on the API's Entity sets and functions tab.

   

Update the OData schema

You can access an editor in the portal to view your API's OData schema. If the API changes, you can also update the schema in API Management from a file or an OData service endpoint.

1. In the portal, navigate to your API Management instance.

2. In the left menu, select APIs > your OData API.

3. On the Entity sets and functions tab, select the context menu (...) next to an entity set or function, and select Edit.

   

4. Review the schema. If you want to update it, select Update from file or Update schema from endpoint.

   

Test your OData API

1. In the left menu, select APIs > your OData API.

2. On the Entity sets and functions tab, select the context menu (...) next to an entity set or function, and select Test.

   

3. In the test console, enter template parameters, query parameters, and headers for your test, and select Test. Learn more about testing an API in the portal.

Secure your OData API

Secure your OData API by applying both existing authentication and authorization policies and an OData validation policy to protect against attacks through OData API requests.

Tip

In the portal, configure policies for your OData API on the API policies tab.

OpenAPI specification

Convert OData metadata to OpenAPI JSON

1. Convert the OData XML to OpenAPI JSON format. Use an OASIS open-source tool for OData v2 or OData v4, depending on your metadata XML.

   The following is an example command to convert OData v2 XML for the test service epm_ref_apps_prod_man_srv:

   odata-openapi -p --basePath '/sap/opu/odata/sap/epm_ref_apps_prod_man_srv' \
    --scheme https --host <your IP address>:<your SSL port> \
    ./epm_ref_apps_prod_man_srv.xml
   

   Note

   • For test purposes with a single XML file, you can use a web-based converter based on the open-source tool.
   • With the tool or the web-based converter, specifying the <IP address>:<port> of your SAP OData server is optional. Alternatively, add this information later in your generated OpenAPI specification or after importing to API Management.

2. Save the openapi-spec.json file locally for import to API Management.

Import and publish backend API

1. From the side navigation menu, under the APIs section, select APIs.

2. Under Create a new definition, select OpenAPI specification.

   

3. Click Select a file, and select the openapi-spec.json file that you saved locally in a previous step.

4. Enter API settings. You can set the values during creation or configure them later by going to the Settings tab.

   • In API URL suffix, we recommend using the same URL path as in the original SAP service.

   • For more information about API settings, see Import and publish your first API tutorial.

5. Select Create.

Note

The API import limitations are documented in another article.

Complete API configuration

Add the following three operations to the API that you imported.

• GET /$metadata

  Operation	Description	Further configuration for operation
  GET /$metadata	Enables API Management to reach the $metadata endpoint, which is required for client integration with the OData server. This required operation isn't included in the OpenAPI specification that you generated and imported.	Add a 200 OK response.

  

• HEAD /

  Operation	Description	Further configuration for operation
  HEAD /	Enables the client to exchange Cross Site Request Forgery (CSRF) tokens with the SAP server, when required. SAP also allows CSRF token exchange using the GET verb. CSRF token exchange isn’t covered in this article. See an example API Management policy snippet to broker token exchange.	N/A

  

• GET /

  Operation	Description	Further configuration for operation
  GET /	Enables policy configuration at service root.	Configure the following inbound rewrite-uri policy to append a trailing slash to requests that are forwarded to service root: <rewrite-uri template="/" copy-unmatched-params="true" /> This policy removes potential ambiguity of requests with or without trailing slashes, which are treated differently by some backends.

  

Also, configure authentication to your backend using an appropriate method for your environment. For examples, see API Management authentication and authorization policies.

Test your API

1. Navigate to your API Management instance.

2. From the side navigation menu, under the APIs section, select APIs.

3. Under All APIs, select your imported API.

4. Select the Test tab to access the test console.

5. Select an operation, enter any required values, and select Send.

   For example, test the GET /$metadata call to verify connectivity to the SAP backend

6. View the response. To troubleshoot, trace the call.

7. When testing is complete, exit the test console.

Production considerations

• See an example end-to-end scenario to integrate API Management with an SAP gateway.
• Control access to an SAP backend using API Management policies. For example, if the API is imported as an OData API, use the validate OData request policy. See also policy snippets for SAP principal propagation and fetching an X-CSRF token.
• For guidance to deploy, manage, and migrate APIs at scale, see:
  • Automated API deployments with APIOps
  • CI/CD for API Management using Azure Resource Manager templates.

Related topics

• API import limitations
• Import an OpenAPI specification
• Import a SOAP API
• Import a SOAP API and convert to REST
• Import an App Service API
• Import a Container App API
• Import a WebSocket API
• Import a GraphQL API
• Import a GraphQL schema and set up field resolvers
• Import an Azure Function App
• Import an Azure Logic App
• Import a Service Fabric service
• Import an OData API
• Import SAP OData metadata
• Import a gRPC API
• Edit an API