[[["容易理解","easyToUnderstand","thumb-up"],["確實解決了我的問題","solvedMyProblem","thumb-up"],["其他","otherUp","thumb-up"]],[["難以理解","hardToUnderstand","thumb-down"],["資訊或程式碼範例有誤","incorrectInformationOrSampleCode","thumb-down"],["缺少我需要的資訊/範例","missingTheInformationSamplesINeed","thumb-down"],["翻譯問題","translationIssue","thumb-down"],["其他","otherDown","thumb-down"]],["上次更新時間：2025-09-03 (世界標準時間)。"],[[["\u003cp\u003eThis document outlines the requirements for integrating an API as a type provider with Deployment Manager, including the need for a valid OpenAPI or Google Discovery descriptor document.\u003c/p\u003e\n"],["\u003cp\u003eThe API must have an accessible descriptor document endpoint that Deployment Manager can reach, either publicly or through basic authentication.\u003c/p\u003e\n"],["\u003cp\u003eDeployment Manager supports APIs that use basic authentication or OAuth 2.0 for APIs hosted on specific Google services.\u003c/p\u003e\n"],["\u003cp\u003eThe API must support Create, Read, Update, and Delete (CRUD) operations via HTTP POST, GET, PUT, and DELETE requests, respectively, and partial support will result in variable behavior.\u003c/p\u003e\n"],["\u003cp\u003eAll path and query parameters within the API must be consistently defined across methods or within the resource body, with considerations for server-generated values and special cases in parameter resolution.\u003c/p\u003e\n"]]],[],null,["# API requirements for Integrating an API\n\n| **Beta**\n|\n|\n| This product or feature is subject to the \"Pre-GA Offerings Terms\" in the General Service Terms section\n| of the [Service Specific Terms](/terms/service-terms#1).\n|\n| Pre-GA products and features are available \"as is\" and might have limited support.\n|\n| For more information, see the\n| [launch stage descriptions](/products#product-launch-stages).\n\nThis document describes general requirements of an API that you want to add as\na type provider to Deployment Manager. Use these guidelines to understand the\ntraits of an API that Deployment Manager expects. If your API doesn't exactly\nmatch the specifications described here, you might be able to resolve these\ninconsistencies using\n[Advanced API Options](/deployment-manager/docs/configuration/type-providers/advanced-configuration-options).\n\nThe API has a valid descriptor document\n---------------------------------------\n\nA descriptor document describes an API and it's resources. Only APIs backed by\nan [OpenAPI specification](https://github.com/OAI/OpenAPI-Specification)\nor a\n[Google Discovery](https://developers.google.com/discovery/v1/reference/apis)\ndescriptor document can be integrated with Deployment Manager. For comprehensive\ninformation on how to create an OpenAPI specification, see the\n[OpenAPI GitHub repo](https://github.com/OAI/OpenAPI-Specification).\n\nAPI descriptor document endpoint is accessible\n----------------------------------------------\n\nDeployment Manager makes an HTTP request to get the descriptor document of the\nAPI, so you should make sure to host your descriptor document somewhere that is\naccessible by Deployment Manager. That can be a publicly available URL or an\nendpoint protected by basic authentication.\n\nAPI accepts basic auth or OAuth2 if hosted on certain Google services\n---------------------------------------------------------------------\n\nDeployment Manager currently supports basic authentication (username and\npassword) and OAuth 2.0 authentication for certain APIs hosted on Google\nKubernetes Engine or on Google Endpoints, you can set up authentication to use\nthe project's service account.\n\nFor more information, read\n[Creating a Type Provider](/deployment-manager/docs/configuration/type-providers/creating-type-provider#authentication).\n\nSupports Create, Read, Update, Delete (CRUD) operations\n-------------------------------------------------------\n\nThe API in question must be a\n[RESTful](https://.wikipedia.org/wiki/Representational_state_transfer)\nAPI that supports CRUD operations. That is, there are methods that perform:\n\n- Create operations - Creates resources. This must be an `HTTP POST` request.\n- Read operations - Gets information about API resources. This must be an `HTTP GET` request.\n- Update operations - Updates a resource. This must be an `HTTP PUT` request\n- Delete operations - Deletes resources. This must be an `HTTP DELETE` request.\n\nAn API that only supports partial CRUD operations will still work but the\nbehavior will be different depending on what operations are available.\n\nAll path and query parameters resolve successfully\n--------------------------------------------------\n\nAll path and query parameters of the API must exist as part of the resource\nbody or exist on all methods of the API, so that Deployment Manager can match\nthe parameter when a user supplies it. The following conditions apply to path\nand query parameters.\n\n**Every path/query parameter for a POST must be a parameter for PUT**\n\nThe following is invalid because `myParameter` exists for `POST` but not for\n`PUT`: \n\n POST /my-api/{myParameter}/resource/{mySecondParameter}\n PUT /my-api/resource/{mySecondParameter} # myParameter is not present\n\n**Every parameter for non-POST method needs to be present either in all the\nmethod interfaces, or as part of the resource, with special considerations if\nthis parameter is generated by the server.**\n\nIn a best case scenario, the API might look like this, where the `name`\nparameter appears for all methods. \n\n POST /my-api/my-resource/{name}\n PUT /my-api/my-resource/{name}\n GET /my-api/my-resource/{name}\n DELETE /my-api/my-resource/{name}\n\nIn another scenario, a field might appear as a path parameter for a method,\nbut not as a path parameter for other methods. In this case, the field should be\npart of the API resource. For example: \n\n POST /my-api/my-resource ← the 'id' field is not present on the POST request\n GET /my-api/my-resource/{id}\n\n schema for my-resource\n type: object\n properties:\n # id is part of the resource so Deployment Manager will use this value for\n # POST requests after creation\n id:\n type: string\n\nIn this example, the assumption is that `id` is a server-generated value\nthat is present on the resource, but not present when making a `POST` request. If\nthe `id` property was required to make a request to an existing resource,\nbut the property was not on resource or available in the path, this causes\nfriction in porting the API to Deployment Manager.\n\nSubtle API behavior requires additional configuration\n-----------------------------------------------------\n\nThere are certain API behaviors that will require additional API configuration\nto integrate the API with Deployment Manager. These behaviors include:\n\n- **Server generated values**: Some API resources have server-generated\n properties that change after each request or when a certain event happens in\n the API. You can use advanced API options to tell Deployment Manager to get\n this new value each time a request is made.\n\n For example, an API might require the latest fingerprint property of a resource\n before it allows an update request. Use\n [Advanced API Options](/deployment-manager/docs/configuration/type-providers/advanced-configuration-options) to tell\n Deployment Manager to get this value each time your user makes a request to\n update a deployment with this.\n- **Manipulating user input**: For example, if your API requires the value of a\n field must always be prefixed with a project ID, you can use input mappings\n to automatically add that information, instead of forcing your users to\n to add it manually.\n\n- **Field values that change with each method**: For methods that reuse the\n same field but with different values, you can use the API options to express\n to Deployment Manager when to use which value.\n\nFor more information, read about\n[Setting Advanced API Options](/deployment-manager/docs/configuration/type-providers/advanced-configuration-options).\n\nWhat's next\n-----------\n\n- Learn how to [create a type provider](/deployment-manager/docs/configuration/type-providers/creating-type-provider).\n- Learn how to [use a type provider](/deployment-manager/docs/configuration/type-providers/calling-type-provider).\n- Learn more about [Advanced API Options](/deployment-manager/docs/configuration/type-providers/advanced-configuration-options).\n- Read about [creating a configuration](/deployment-manager/docs/configuration).\n- [Create a deployment](/deployment-manager/docs/deployments)."]]
