Manage your web API via Restlet Cloud Connectors
Restlet Cloud can bring additional features to your existing web API hosted outside of Restlet Cloud with the Connector cell.
Enhance your web API
With a Connector, you can add and configure the following features to your API:
- Authenticated access
- Fine-grained access control
- Rate-limitation (quotas) to your API users
- IP filtering
How does a connector work?
A connector is split into two parts: a Connector Cell and a Restlet Cloud Agent.
The Connector Cell is defined in the Restlet Cloud console and holds the configuration of the desired features.
The Restlet Cloud Agent is set in front of your API, accesses this configuration, acts as a Reverse Proxy and provides the features you have enabled in the Restlet Cloud console on the incoming requests of your API.
You can either decide to host the agent on your own Information System or to host it directly on Restlet Cloud:
By default, Restlet Cloud hosts the agent. A hosted agent will be running directly within Restlet Cloud and will allow you to add management features to your API by proxying its traffic. if you choose hosted agent Deployment mode, you will be asked to choose a domain on restlet.net. A default HTTPS endpoint will be created using that domain.
A standalone agent can be downloaded and run on your own infrastructure in order to reduce lag as much as possible as the agent is very close to your hosted API. This agent allows you to add management features to your API by proxying its traffic.
Create a Connector cell
To create a Connector, go to the Dashboard and click on the +Web API button.
In the Create a web API window, select Connector from the Type drop-down menu.
Select the appropriate Deployment mode:
The default configuration is Hosted agent. You are prompted to give your Connector a Name and a Description (optional). The Domain field is filled in automatically on the basis of the Name entered. If the domain is not available, a message informs you that you need to choose a unique domain.
From the Settings tab, select the Remote agent menu from the Connector section. Enter a Target endpoint for your agent.
Note: Your target endpoint must not end up with a trailing slash "/".
You will be prompted to give your Connector a Name and a Description (optional).
A Connector has the same properties as a web API except that a Connector is not hosted by Restlet Cloud.
With a Connector you can also document your web API as with a Descriptor.
Once you have created a Connector, you can configure it and install the Remote Agent in your Information System (if you choose the standalone agent configuration), and that's all.
Your web API has new features inside without writing a line of code!
Add a format to a representation
Navigate to the Settings tab. From the Formats section in the left panel, click the Add button. Enter a Name, one or several media type(s) and select the Favorite format checkbox if you want this format to be added to each new representation by default.
Add a custom sample value to a representation
From the Overview tab, select the chosen representation from the left panel. In the central panel, click on the appropriate format and select its Custom sample checkbox. You can then edit the sample in the text field above and Save.
Once you have saved your custom sample, you will retrieve it in read-only mode in the Resources section.
To go back to the default sample value, deselect the Custom sample checkbox and Save.
Note: Custom sample values are not supported for input representations or method responses of list Type.
Import a Swagger or RAML definition
You can import a Swagger or RAML definition by providing the definition's URL or file. Swagger 1.2, Swagger 2.0 and RAML 0.8 are supported.
From the Dashboard, open an existing Connector or create a new one by clicking on + Web API and selecting Connector from the drop-down menu.
From the Connector's Overview, click on the cog button on the top right of your screen and select Import definition from the menu.
You will be prompted to select the file that contains your API's definition or to enter the URL that points to it. Swagger 1.2, Swagger 2.0 and RAML 0.8 are supported.
Click on the Import button to import the Swagger or RAML definition into your Connector. As a result, representations and resources will be added to your Connector according to the content of the definition.
To view the changes, navigate to the Connector's Overview tab.
Import a multi-file definition
You can import a multi-file definition by uploading a zip archive.
Click on Choose a file and browse to the zip archive you have chosen.
From the Main definition file drop-down menu, select the main file at the root of your API definition.
Switch a connector cell deployment mode
It is possible to switch between hosted or standalone configurations.
Switch from standalone agent to hosted agent deployment mode requires that you specify a domain name if one was not already chosen.
Note: If you switch back to standalone agent configuration, the domain name is still reserved to this connector in case you would want to switch back.
Domain creation is subject to the same rules as for full stack APIs. This also results in the creation of a new HTTPS endpoint that uses this domain.
Navigate to the Settings tab and select Agent details from the Connector section. Choose the Hosted agent or Standalone agent configuration from the Deployment mode drop-down menu.
Save your changes and Deploy your Connector so that your latest changes are taken into account.