Written for Frends version 5.6.
Frends has API management. This enables the user to create and manage HTTP Processes that implement an operation in an OpenAPI 2.0 (Swagger) specification.
Creating a swagger description of the API
OpenAPI specification can be found at https://swagger.io/specification/#schema
The swagger file can be created using (NOTE: Not necessarily secure, so recommended only for testing) http://editor.swagger.io/#
The swagger defines how the API works.
Frends can work with swagger files in JSON format, not in YAML.
This example swagger defines an API that allows fetching product information with an EAN code and returns one of two types of messages
{
"swagger": "2.0",
"info": {
"description": "This API interface is for product data from backend system.",
"version": "1.0.0",
"title": "Customer Data Interface V1",
"contact": {
"name": "Frank von Freundlich",
"email": "frank@someserver.com"
}
},
"host": "frends44.frendsapp.com",
"basePath": "/api/f44_demo",
"schemes": [
"http"
],
"paths": {
"/GetProduct_v1": {
"get": {
"description": "Gets information based on product code",
"parameters": [
{
"name": "prod_code",
"in": "query",
"description": "Product code (EAN)",
"required": true,
"type": "number",
"format": "integer"
}
],
"responses": {
"200": {
"description": "Successful response",
"schema": {
"title": "SERVICE",
"type": "object",
"properties": {
"TYPE": {
"type": "string",
"default": "response",
"description": "Message type."
},
"DATA": {
"title": "DATA",
"type": "object",
"properties": {
"Product_code": {
"type": "string",
"default": "",
"description": "Product code (EAN) from the backend system."
},
"Description": {
"type": "string",
"default": "",
"description": "Description of the product."
},
"Inventory": {
"type": "integer",
"default": "",
"description": "How many units are in the inventory."
},
"Weight": {
"type": "integer",
"default": "",
"description": "Weight per unit."
},
"Price": {
"type": "integer",
"default": "",
"description": "Price per unit."
}
}
}
}
}
},
"400": {
"description": "Failed response",
"schema": {
"title": "SERVICE",
"type": "object",
"properties": {
"TYPE": {
"type": "string",
"default": "response",
"description": "Message type."
},
"ERROR": {
"title": "ERROR",
"type": "object",
"properties": {
"Error_code": {
"type": "integer",
"default": "",
"description": "Error code."
},
"Error_message": {
"type": "string",
"default": "",
"description": "Error message."
}
}
}
}
}
}
}
}
}
}
}
Setting up API in FRENDS
Copy the swagger json to Frends and create a new API and paste the json to the swagger editor. Next press Save changes to create the API.
You should then see your API appear in the API List.
2. Create a Process for the API by first clicking on the API to show all available actions and URLs.
Then click on the desired action to see its description and the option to create a new Linked Process.
Click on the 'Create new Process' button and a Frends Process Editor will open. The Process Editor is based on the information provided in the swagger. In our swagger we have defined two possible responses as well as the used method.
If you click through the Elements, you will see in practice how the swagger parameters have been used.
Looking at the values, some probably need to be adjusted for this interface to be useful. For example, returning '0' for the inventory of all products is probably not what is truly wanted. For now, let's just create a simple dummy Process that will always return a successful response.
Now click 'Create new Process and activate it'. The Process will appear in the Process List with an 'API' Trigger.
We can also now see the Process in the 'APIs' page under the 'GET /GetProduct_v1' interface.
3. Deploy Processes from the API View by clicking the deploy button. The following popup will appear:
From here you can give the API a description and check active operations. The show button will open the Process associated with the operation in a new browser tab.
Clicking the save and deploy button gives us a popup where we can choose the Environment we wish to deploy to, the version we wish to deploy and the option to activate Triggers if they're not already active (checked by default).
If we now click deploy, the API will (if successfully deployed) appear in the test Environment's API List.
4. Create API Key. Go to Administration → API Keys.
The page defaults to API Keys View with existing API Keys listed under the 'New API Key' button and the filter box. Click on 'New API Key' to create the key you want:
At the moment there is no ruleset to attach to this API Key, so all you can do is give it a name and assign an Environment. The API Key will appear once you click 'Save'.
5. Create API ruleset. For the API Key to be of use, you need to define a ruleset with which to use it. This is done by going to the 'API rulesets', then choosing 'New Ruleset' and filling out the appearing form:
Here the ruleset has been given a suitable name and description. The API Key that was just created has been added to the list of API Keys and a rule for the allowed method is about to be defined. If the customer data interface had more functionality than the get operation defined in the swagger, you could include all rules in this single ruleset as well as allow the use of more than one API Keys. If you want to have different accessibility with different API Keys - say an API Key that you can only use to fetch data and another that also allows posting data - you need to create different rulesets for each Key. Once you click save changes, the ruleset will automatically appear in the ruleset list of the chosen API Key.
