// This module is used in the following assemblies:
// as_adding-api-connectors.adoc

[id='creating-rest-api-connectors_{context}']
= Creating REST API client connectors

Upload an OpenAPI document to enable {prodname} to create a REST API
client connector. 

.Prerequisite
You have an OpenAPI document for the connector that you want
{prodname} to create.

.Procedure

. In the {prodname} navigation panel, click *Customizations* > 
*API Client Connectors*. Any API client connectors that are
already available are listed here.
. Click *Create API Connector*.
. On the *Create API Connector* page, do one of the following:
+
* Click in the dotted-line box and select the OpenAPI file that you want to upload.
* Select *Use a URL* and paste the URL for the OpenAPI document
in the input field. 

. Click *Next*. If there is invalid or missing content, {prodname}
displays information about what needs to be corrected. Select a different
OpenAPI file to upload or click *Cancel*,
revise the OpenAPI file, and upload the updated file.
+
If the schema is valid, {prodname} displays a summary of
the operations that the connector provides. This might include errors and
warnings about the operation definitions.

. If you are satisfied with the summary, click *Next*.
+
Or, to revise the OpenAPI document, click *Review/Edit* 
to open the API Designer editor. Update the schema as needed. For details about using the API editor, see 
link:{LinkDesigningAPIs}#create-api-definition[Design and develop an API definition with API Designer]. When you are done, *Save* your changes to incorporate your updates into the 
new API client connector. Then click *Next* to continue creating the 
API client connector. 
+
Sometimes, if you provide a URL for the OpenAPI document, {prodname} 
can upload it but  cannot open it for editing. Typically, this is caused by 
settings on the file’s host. To open the schema for editing, 
{prodname} requires that the file host has:

* An `https` URL. (An `http` URL does not work.)
* Enabled CORS. 

. Indicate the API's security requirements. {prodname} reads the 
OpenAPI definition to determine the information needed to 
configure the connector to meet the API’s security requirements. 
{prodname} can display any of the following: 

.. *No Security*
.. *HTTP Basic Authorization* — If the API service uses 
HTTP basic authorization, 
select this checkbox. Later, when you use this 
connector to create a connection, {prodname} prompts you to 
enter a user name and password.
.. *OAuth 2.0*  — {prodname} prompts you to enter:
... *Authorization URL* is the location for registering {prodname} as
a client of the API. Registration authorizes {prodname} to access the API.
See link:{LinkSyndesisConnectorGuide}#register-with-rest-api_rest[{NameOfSyndesisConnectorGuide}, Registering {prodname} as a REST API client]. 
The OpenAPI document or other
documentation for the API should specify this URL. If it does not then
you must contact the service provider to obtain this URL.
... *Access Token URL* is required for OAuth authorization. Again, the
OpenAPI document or other documentation for the API should provide
this URL. If it does not then you must contact the service provider.
.. *API Key* — If the API service requires an API key, {prodname} 
prompts for any information that it needs to create the connector. 
Prompts are based on the OpenAPI definition. For example, 
you might need to indicate if the API key is in message headers 
or in query parameters. If the OpenAPI definition specifies 
API key security, as well as another security type, select the
checkbox to indicate that you want to use API key security in 
connections based on this connector. Later, when you use this 
connector to create a connection, {prodname} prompts you to 
enter the value of an API key. 

. Click *Next*. {prodname} displays the connector's name,
description, host, and base URL as indicated by the OpenAPI document.
For connections that you create from this connector,
+
** {prodname}
concatenates the host and base URL values to define the endpoint for
the connection. For example, if the host is `\https://example.com` and
the base URL is `/api/v1` then the connection endpoint is
`\https://example.com/api/v1`.
** {prodname} applies the OpenAPI document to data
mapping steps. If the OpenAPI document supports more than one schema then {prodname}
uses the TLS (HTTPS) schema.
. Review the connector details and optionally upload an icon for the connector.
If you do not upload an icon, {prodname} generates one.
You can upload an icon at a later time. When {prodname} displays
the flow of an integration, it displays a connector's icon
to represent connections that are created from that connector.

. To override a value obtained from
the OpenAPI file, edit the field value that you want to change.
+
[IMPORTANT]
After {prodname} creates a connector,
*you cannot change it*. To effect a change, you need to upload an updated
OpenAPI document so that {prodname} can create a new connector
or you can upload the same schema and then edit it in the API editor. 
You then continue the process for creating a new API client connector. 

. When you are satisfied with the connector details, click *Save*.
{prodname} displays the new connector in the list of API Client Connectors. 

.Next step
For details about using your new API connector, see
link:{LinkSyndesisConnectorGuide}#connecting-to-api-clients_connectors[{NameOfSyndesisConnectorGuide}, Connecting to API clients]. 
