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

[id='about-api-client-connectors_{context}']
= Requirements for REST API client connectors

After you upload an OpenAPI schema to {prodname}, a connector to the REST API
becomes available. You can select the connector to create
a REST API client connection. You can then create a new integration and 
add the REST API client connection, or you can edit an existing integration 
to add the REST API client connection. 

{prodname} connectors support OAuth 2.0, HTTP basic
authorization, and API keys. If access to the REST API requires Transport Layer Security (TLS)
then the API needs to use a valid certificate that is issued by
a recognized Certificate Authority (CA).

A REST API that uses OAuth must have an authorization URL that takes a client
callback URL as input. After {prodname} creates the connector and before you
use the connector to create a connection, you must visit that URL to 
register your {prodname} environment as a client of the REST API.
This authorizes your {prodname} environment to access the REST API. As part
of registration, you provide the {prodname} callback URL. 
The details for doing this are described in
link:{LinkSyndesisConnectorGuide}#register-with-rest-api_rest[{NameOfSyndesisConnectorGuide}, Registering {prodname} as a REST API client].

For a REST API that uses OAuth, {prodname} supports only the 
*Authorization Code* grant flow for obtaining authorization. 
In the OpenAPI document that you upload to 
create the connector, in the OAuth `securityDefinitions` object, 
you must set the `flow` attribute to `accessCode`, for example:

----
securityDefinitions:
  OauthSecurity:
    type: oauth2
    flow: accessCode
    authorizationUrl: 'https://oauth.simple.api/authorization'
    tokenUrl: 'https://oauth.simple.api/token'
----
You must not set 
`flow` to `implicit`, `password`, or `application`. 

The OpenAPI schema for a REST API client connector cannot have cyclic schema 
references. For example, a JSON schema that specifies a request or 
response body cannot reference itself as a whole nor reference any 
part of itself through any number of intermediate schemas.

{prodname} cannot create connectors for REST APIs that support the HTTP 2.0
protocol.
