Best Practices for Adding a Type Provider

This page describes best practices for creating a new API to add to Deployment Manager as a Type Provider or adding an existing API as a type provider.

Deployment Manager lets you add APIs as type providers to expose the API resources as types that you can call in their configuration. To make the process easier for you, use these best practices when configuring or creating an API.

Building a new API

If you are building a new API that you intend to integrate with Deployment Manager, use these best practices.

Use standard Create, Read, Update, and Delete (CRUD) methods and avoid custom methods

Avoid creating custom methods if possible. Stick to standard REST methods such as GET, POST, PUT, and DELETE methods. These methods are recognized by Deployment Manager and can be automatically mapped.

For Discovery APIs, you should name your API methods according to the following mapping:

REST method Recommended API naming
POST create or insert
GET get
PUT update
DELETE delete

For OpenAPI specifications, you cannot name your API methods differently than the standard REST methods.

Use predictable resource paths

For OpenAPI specifications, Deployment Manager supports two behaviors to identify a RESTful interface. The first is if all REST methods for a resource belong in the same resource path:

/foo/{name}
  post:
  get:
  delete:
  put:

If you must separate the methods, use the same resource path. For example, the following is valid because it refers to the same /foo resource:

/foo/
  post:
/foo/{id}
  get:
  delete:
  put:

However, the following is invalid because it refers to two different resources from the view of Deployment Manager:

/foo/
 post:
/foo-bar/{id}:
 get:
 put:
 delete:

For rare cases, you might tempted to name your resource paths like so:

foo/create
  post:

foo/delete
  delete:

This is invalid from Deployment Manager's view because it cannot identify the RESTful interface.

Use consistent naming across the interface

Keep input and path names the same between POST and PUT methods. This also applies for the parameter values as well. That is, keep the syntax for parameter values the same across methods.

For example, if you have a parameter named email for the request body of a POST request, don't name the same parameter emailAddress for the PUT request.

POST
{
    “email”: “my-email”
}

PUT
{
    “email”: “my-email@gmail.com”
}

If you must add this type of behavior, tell Deployment Manager how to handle this behavior by setting advanced API options.

In addition, keep the request body for POST and PUT methods the same. For GET and DELETE methods, only the path is applicable as there is no request body for these methods.

Integrating an existing API

Integrating an existing API can be a widely varied process depending on the API. As such, there is no concrete set of best practices that can be applied generically across all APIs. The following is a list of general advice that might help when considering ways to integrate an existing API.

  • Use an API wrapper for non-RESTful APIs.

    If an existing API is not a RESTful API, you can create an API wrapper to expose the REST methods only.

  • If the API is almost RESTful, identify and update the API.

    If your API is almost RESTful and only has a few non-REST behaviors, you could update the API to resolve these behaviors.

  • Server generated values always requires an input mapping.

    If your API has server-generated values that are required by API methods, you will need to set up input mappings to get the server-generated value and map it for each request.

What's next