// This module is included in the following assemblies:
// as_developing-rest-api-client-connectors.adoc

[id='guidelines-for-openapi-documents_{context}']
= Guidelines for OpenAPI schemas for REST API client connectors

When {prodname} creates a REST API client connector, it maps each resource
operation in the OpenAPI document to a connection action. The action name
and action description come from documentation in the OpenAPI document.

The more detail that the OpenAPI document provides, the more support
{prodname} can offer when connecting to the API. For example,
the API definition is not required to declare data types for requests
and responses. Without type declarations, {prodname}
defines the corresponding connection action as typeless. However, in an
integration, you cannot add a data mapping step immediately before or
immediately after an API connection that performs a typeless action.

One remedy for this is to add more information to the OpenAPI document.
Identify the OpenAPI resource operations that
will map to the actions you want the API connection to perform. In the
OpenAPI document, ensure that there is a YAML or JSON schema that specifies
each operation's request and response types.

After you upload the schema, {prodname} gives you an opportunity 
to review and edit it in API Designer, which is a visual editor for 
designing APIs based on the OpenAPI document. You can add more detail, 
save  your updates, and {prodname} creates an API client connector that 
incorporates your updates. 
After {prodname} creates the client connector, you can no longer edit 
the OpenAPI document. To implement a change, you must create a new 
client connector. 

If the OpenAPI document for the API declares support for
`application/json` content type and also `application/xml` content type
then the connector uses the JSON format. If the OpenAPI document
specifies `consumes` or `produces` parameters that define both
`application/json` and `application/xml`, 
then the connector uses the JSON format.
