Merge pull request #240142 from dlepow/odataapi

[APIM] Import OData API

Author: v-dirichards

articles/api-management/TOC.yml

@@ -247,6 +247,8 @@
                   href: import-logic-app-as-api.md
                 - name: Configure Service Fabric backend
                   href: how-to-configure-service-fabric-backend.md
+                - name: Import OData API
+                  href: import-api-from-odata.md
                 - name: Import SAP OData metadata
                   href: sap-api.md
                 - name: Configure API for SSE
@@ -558,6 +560,8 @@
               href: validate-headers-policy.md
             - name: validate-jwt
               href: validate-jwt-policy.md
+            - name: validate-odata-request
+              href: validate-odata-request-policy.md
             - name: validate-parameters
               href: validate-parameters-policy.md
             - name: validate-status-code

articles/api-management/api-management-policies.md

@@ -95,6 +95,7 @@ More information about policies:
 
 - [Validate content](validate-content-policy.md) - Validates the size or content of a request or response body against one or more API schemas. The supported schema formats are JSON and XML.
 - [Validate GraphQL request](validate-graphql-request-policy.md) - Validates and authorizes a request to a GraphQL API. 
+- [Validate OData request](validate-odata-request-policy.md) - Validates a request to an OData API to ensure conformance with the OData specification.
 - [Validate parameters](validate-parameters-policy.md) - Validates the request header, query, or path parameters against the API schema.
 - [Validate headers](validate-headers-policy.md) - Validates the response headers against the API schema.
 - [Validate status code](validate-status-code-policy.md) - Validates the HTTP status codes in responses against the API schema.

articles/api-management/import-api-from-odata.md

@@ -0,0 +1,76 @@
+---
+title: Import an OData API to Azure API Management | Microsoft Docs
+description: Learn how to import an OData API to an API Management instance using the Azure portal.
+services: api-management
+author: dlepow
+
+ms.service: api-management
+ms.topic: how-to
+ms.date: 06/06/2023
+ms.author: danlep
+ms.custom: 
+---
+# Import an OData API
+
+This article shows how to import an OData-compliant service as an API in API Management. 
+
+In this article, you learn how to:
+> [!div class="checklist"]
+> * Import an OData metadata description using the Azure portal
+> * Manage the OData schema in the portal
+> * Secure the OData API
+
+> [!NOTE]
+> Importing an OData service as an API is in preview. Currently, testing OData APIs isn't supported in the test console of the Azure portal or in the API Management developer portal.
+
+## Prerequisites
+
+* An API Management instance. If you don't already have one, complete the following quickstart: [Create an Azure API Management instance](get-started-create-service-instance.md).
+
+* A service exposed as OData v2 or v4.
+
+[!INCLUDE [api-management-navigate-to-instance.md](../../includes/api-management-navigate-to-instance.md)]
+
+## Import OData metadata
+
+1. In the left menu, select **APIs** > **+ Add API**.
+1. Under **Create from definition**, select **OData**.
+
+    :::image type="content" source="media/import-api-from-odata/odata-api.png" alt-text="Screenshot of creating an API from an OData description in the portal." :::
+1. 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.
+
+    1. Enter remaining settings to configure your API. These settings are explained in the [Import and publish your first API](import-and-publish.md#import-and-publish-a-backend-api) tutorial.
+1. 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 **Schema** tab. 
+
+    :::image type="content" source="media/import-api-from-odata/odata-schema.png" alt-text="Screenshot of schema of OData API in the portal." :::    
+
+## 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](https://portal.azure.com), navigate to your API Management instance.
+1. In the left menu, select **APIs** > your OData API.
+1. On the **Schema** tab, select the edit (**\</>**) icon.
+1. Review the schema. If you want to update it, select **Update from file** or **Update schema from endpoint**.
+
+    :::image type="content" source="media/import-api-from-odata/odata-schema-update.png" alt-text="Screenshot of schema editor for OData API in the portal." :::    
+
+## Secure your OData API
+
+Secure your OData API by applying both existing [access control policies](api-management-policies.md#access-restriction-policies) and an [OData validation policy](validate-odata-request-policy.md) to protect against attacks through OData API requests.
+
+> [!TIP]
+> In the portal, configure policies for your OData API on the **API policies** tab.
+
+[!INCLUDE [api-management-append-apis.md](../../includes/api-management-append-apis.md)]
+
+[!INCLUDE [api-management-define-api-topics.md](../../includes/api-management-define-api-topics.md)]
+
+## Next steps
+
+> [!div class="nextstepaction"]
+> [Transform and protect a published API](transform-api.md)

articles/api-management/media/import-api-from-odata/odata-api.png

@@ -6,7 +6,7 @@ ms.service: api-management
 author: martinpankraz
 ms.author: mapankra
 ms.topic: how-to
-ms.date: 01/26/2022
+ms.date: 06/06/2023
 ms.custom: 
 ---
 
@@ -21,6 +21,9 @@ In this article, you'll:
 > * Complete API configuration
 > * Test the API in the Azure portal
 
+> [!NOTE]
+> In preview, API Management can now directly import an OData API from its metadata description, without requiring conversion to an OpenAPI specification. [Learn more](import-api-from-odata.md).
+
 ## Prerequisites
 
 - An existing API Management instance. [Create one if you haven't already](get-started-create-service-instance.md).

articles/api-management/media/import-api-from-odata/odata-schema-update.png

@@ -12,7 +12,7 @@ ms.author: danlep
 
 # Validate GraphQL request
 
-The `validate-graphql-request` policy validates the GraphQL request and authorizes access to specific query paths. An invalid query is a "request error". Authorization is only done for valid requests. 
+The `validate-graphql-request` policy validates the GraphQL request and authorizes access to specific query paths in a GraphQL API. An invalid query is a "request error". Authorization is only done for valid requests. 
 
 [!INCLUDE [api-management-policy-generic-alert](../../includes/api-management-policy-generic-alert.md)]
 
@@ -68,24 +68,28 @@ Available actions are described in the following table.
 ## Usage
 
 - [**Policy sections:**](./api-management-howto-policies.md#sections) inbound
-- [**Policy scopes:**](./api-management-howto-policies.md#scopes) global, product, API, operation
+- [**Policy scopes:**](./api-management-howto-policies.md#scopes) global, workspace, product, API
 -  [**Gateways:**](api-management-gateways-overview.md) dedicated, consumption, self-hosted
 
 ### Usage notes
 
-Because GraphQL queries use a flattened schema, permissions may be applied at any leaf node of an output type: 
-
-* Mutation, query, or subscription
-* Individual field in a type declaration 
-
-Permissions may not be applied to:
- 
-* Input types
-* Fragments
-* Unions
-* Interfaces
-* The schema element  
- 
+* Configure the policy for a [pass-through](graphql-api.md) or [synthetic](graphql-schema-resolve-api.md) GraphQL API that has been imported to API Management.
+
+* This policy can only be used once in a policy section.
+
+* Because GraphQL queries use a flattened schema, permissions may be applied at any leaf node of an output type: 
+
+    * Mutation, query, or subscription
+    * Individual field in a type declaration 
+    
+    Permissions may not be applied to:
+     
+    * Input types
+    * Fragments
+    * Unions
+    * Interfaces
+    * The schema element  
+     
 ## Error handling
 
 Failure to validate against the GraphQL schema, or a failure for the request's size or depth, is a request error and results in the request being failed with an errors block (but no data block). 

articles/api-management/media/import-api-from-odata/odata-schema.png

@@ -0,0 +1,60 @@
+---
+title: Azure API Management policy reference - validate-odata-request | Microsoft Docs
+description: Reference for the validate-odata-request policy available for use in Azure API Management. Provides policy usage, settings, and examples.
+services: api-management
+author: dlepow
+
+ms.service: api-management
+ms.topic: article
+ms.date: 06/06/2023
+ms.author: danlep
+---
+
+# Validate OData request
+
+The `validate-odata-request` policy validates the request URL, headers, and parameters of a request to an OData API to ensure conformance with the [OData specification](https://www.odata.org/documentation).
+
+> [!NOTE]
+> This policy is currently in preview.
+
+## Policy statement
+
+```xml
+<validate-odata-request error-variable-name="variable name" default-odata-version="OData version number" min-odata-version="OData version number" max-odata-version="OData version number" max-size="size in bytes" />
+```
+
+## Attributes
+
+| Attribute         | Description                                            | Required | Default |
+| ----------------- | ------------------------------------------------------ | -------- | ------- |
+| error-variable-name | Name of the variable in `context.Variables` to log validation errors to.  |   No    | N/A   |
+| default-odata-version | The default OData version that is assumed for parameter validation if the request doesn't contain an `OData-Version` header.  | No  | 4.0 |
+| min-odata-version | The minimum OData version in the `OData-Version` header of the request that the policy accepts. | No  | N/A |
+| max-odata-version | The maximum OData version in the `OData-Version` header of the request that the policy accepts. | No  | N/A |
+| max-size | Maximum size of the request payload in bytes.  |  No      | N/A   |
+
+
+## Usage
+
+- [**Policy sections:**](./api-management-howto-policies.md#sections) inbound
+- [**Policy scopes:**](./api-management-howto-policies.md#scopes) global, workspace, product, API
+-  [**Gateways:**](api-management-gateways-overview.md) dedicated, consumption, self-hosted
+
+### Usage notes
+
+* Configure the policy for an OData API that has been [imported](import-api-from-odata.md) to API Management. 
+* This policy can only be used once in a policy section.
+
+## Example
+
+The following example validates a request to an OData API and assumes a default OData version of 4.01 if no `OData-Version` header is present:
+
+```xml
+<validate-odata-request default-odata-version="4.01" />  
+```
+
+## Related policies
+
+* [Validation policies](api-management-policies.md#validation-policies)
+
+[!INCLUDE [api-management-policy-ref-next-steps](../../includes/api-management-policy-ref-next-steps.md)]

articles/api-management/sap-api.md

@@ -8,8 +8,9 @@ ms.author: vlvinogr
 ## Append other APIs
 
 You can compose an API of APIs exposed by different services, including:
-* The OpenAPI Specification
+* An OpenAPI specification
 * A SOAP API
+* A GraphQL API
 * A Web App hosted in Azure App Service
 * Azure Function App
 * Azure Logic Apps