API requirements for Integrating an API

This document describes general requirements of an API that you want to add as a type provider to Deployment Manager. Use these guidelines to understand the traits of an API that Deployment Manager expects. If your API doesn't exactly match the specifications described here, you might be able to resolve these inconsistencies using Advanced API Options.

The API has a valid descriptor document

A descriptor document describes an API and it's resources. Only APIs backed by an OpenAPI specification or a Google Discovery descriptor document can be integrated with Deployment Manager. For comprehensive information on how to create an OpenAPI specification, see the OpenAPI GitHub repo.

API descriptor document endpoint is accessible

Deployment Manager makes an HTTP request to get the descriptor document of the API, so you should make sure to host your descriptor document somewhere that is accessible by Deployment Manager. That can be a publicly available URL or an endpoint protected by basic authentication.

API accepts basic auth or OAuth2 if hosted on certain Google services

Deployment Manager currently supports basic authentication (username and password) and OAuth 2.0 authentication for certain APIs hosted on Google Kubernetes Engine or on Google Endpoints, you can set up authentication to use the project's service account.

For more information, read Creating a Type Provider.

Supports Create, Read, Update, Delete (CRUD) operations

The API in question must be a RESTful API that supports CRUD operations. That is, there are methods that perform:

Create operations - Creates resources. This must be an HTTP POST request.
Read operations - Gets information about API resources. This must be an HTTP GET request.
Update operations - Updates a resource. This must be an HTTP PUT request
Delete operations - Deletes resources. This must be an HTTP DELETE request.

An API that only supports partial CRUD operations will still work but the behavior will be different depending on what operations are available.

Supports `GET` requests	Supports `CREATE` requests	Supports `UPDATE` requests	Supports `DELETE` requests	Special API behavior?
Yes	Yes	Yes	Yes	None.
Yes	Yes	Yes	No	Users can abandon a resource but cannot delete it.
Yes	Yes	No	Yes	Any changes to an existing resource would fail. Users would need to delete and recreate a resource to update it.
Yes	Yes	No	No	Both of behaviors described above.
Yes	No	Yes	Yes	If an API does not support create requests, users can add existing resources to the deployment by updating the deployment with the `ACQUIRE` policy.
Yes	No	Yes	No	Users can acquire a resource or update a resource after it has been acquired but the resource cannot be deleted.
Yes	No	No	Yes	Users can delete a resource and get a resource, or can add an existing resource to a deployment.
Yes	No	No	No	Users can acquire an existing resource or remove it with the `ABANDON` policy.

All path and query parameters resolve successfully

All path and query parameters of the API must exist as part of the resource body or exist on all methods of the API, so that Deployment Manager can match the parameter when a user supplies it. The following conditions apply to path and query parameters.

Every path/query parameter for a POST must be a parameter for PUT

The following is invalid because myParameter exists for POST but not for PUT:

POST  /my-api/{myParameter}/resource/{mySecondParameter}
PUT   /my-api/resource/{mySecondParameter}  # myParameter is not present

Every parameter for non-POST method needs to be present either in all the method interfaces, or as part of the resource, with special considerations if this parameter is generated by the server.

In a best case scenario, the API might look like this, where the name parameter appears for all methods.

POST   /my-api/my-resource/{name}
PUT    /my-api/my-resource/{name}
GET    /my-api/my-resource/{name}
DELETE /my-api/my-resource/{name}

In another scenario, a field might appear as a path parameter for a method, but not as a path parameter for other methods. In this case, the field should be part of the API resource. For example:

POST  /my-api/my-resource ← the 'id' field  is not present on the POST request
GET   /my-api/my-resource/{id}

schema for my-resource
type: object
properties:
# id is part of the resource so Deployment Manager will use this value for
# POST requests after creation
  id:
    type: string

In this example, the assumption is that id is a server-generated value that is present on the resource, but not present when making a POST request. If the id property was required to make a request to an existing resource, but the property was not on resource or available in the path, this causes friction in porting the API to Deployment Manager.

Subtle API behavior requires additional configuration

There are certain API behaviors that will require additional API configuration to integrate the API with Deployment Manager. These behaviors include:

Server generated values: Some API resources have server-generated properties that change after each request or when a certain event happens in the API. You can use advanced API options to tell Deployment Manager to get this new value each time a request is made.

For example, an API might require the latest fingerprint property of a resource before it allows an update request. Use Advanced API Options to tell Deployment Manager to get this value each time your user makes a request to update a deployment with this.
Manipulating user input: For example, if your API requires the value of a field must always be prefixed with a project ID, you can use input mappings to automatically add that information, instead of forcing your users to to add it manually.
Field values that change with each method: For methods that reuse the same field but with different values, you can use the API options to express to Deployment Manager when to use which value.

For more information, read about Setting Advanced API Options.