[Reading time: 5 minutes]
Overview
A web service is an API that operates over the web, using standardized protocols (e.g., HTTP).
Web services allow for making requests to external services in order to integrate data or interact with third-party APIs. They are configurable in the Maker and can be called in different contexts within the platform.
Types of web services
There are two types of web services in INO cx:
- Standard: Web services directly configurable by the user via the Maker.
- Customized: Developed specifically for custom needs and not directly modifiable through the interface.
Configuring a web service
1. Creating a Web Service
In the Maker, go to the Data module, then the web services submodule. You will arrive at the list of previously created web services.
Click Create. A configuration window will appear, where several parameters must be defined:
2. Required parameters
- Type:
- Standard: Manual configuration.
- Customized: Services developed specifically for advanced needs.
- Name: The identifier for the web service.
- Reference: Must be unique and can contain special characters (_ . + @ -).
- HTTP method: The type of request that determines the interaction with the external API:
- POST (sending new data)
- GET (retrieving information)
- PUT (updating an existing resource)
- PATCH (partially modifying a resource)
- DELETE (deleting a resource)
- INVOKE (executing a specific action defined by the external API)
- URL: The target URL of the web service, which can include dynamic variables (e.g., https://api.example.com/$$user$$). These variables are replaced by values during the request execution.
- Authentication:
- None
- Basic (username and password)
- Bearer (authentication token)
- Password: Must contain between 0 and 128 characters.
3. Environments
Customized web services can be associated with specific environments (Development, Production). This allows testing integrations before deploying them to production.
Managing web services
Once created, web services appear in a list containing the following information:
- Type (Standard or Customized)
- Name
- HTTP method used
- Authentication type
- Target URL
- Customized web service (if applicable)
- Associated environment (if applicable)
The limit on web service creation is set at 50. See the article on limits for more details.
You can then access the web service to add information under two tabs: settings and history.
Settings
1. Request headers
HTTP headers allow for transmitting additional information with the request (optional). Each header is a key/value pair, for example:
- Content-Type: application/json to indicate that the request body is in JSON format.
- Accept-Language: fr to specify the language in which the response should be returned by the API (useful for multilingual APIs).
2. Request body
The request body contains the data sent to the target API, usually in JSON format.
The body can also contain dynamic variables that will be replaced during request execution.
When the value is a variable, it means that the value associated with the key can change or be dynamically calculated, rather than being a fixed value.
For example, with a variable as a value:
Let’s assume we are keeping a record of users in an application, and we want to associate a key (e.g., the username) with a value representing the age of that user. If the age changes over time, we can use a variable to keep that information updated.
Example:
- Key: “Alice”
- Value (variable): age (where age could be, for instance, 25 initially, and then become 26 the following year).
3. Response Data Collection
Once the request is made, INO cx allows you to extract certain data returned by the API for reuse.
- Key: The field in which to store the retrieved value.
- Value: A JSON expression that allows access to a specific element in the API response.
Example of an API response:
{
"data": {
"id": 1001,
"name": "Product A",
"price": 25.50
}
}
To retrieve the product name and price in INO cx:
- Key:
product_name➡️ Value:$$.data.name$$ - Key:
product_price➡️ Value:$$.data.price$$
The $$ notation is used to dynamically reference elements in the API response. These values can then be displayed in the interface or used in other automated actions.
History
The history tab allows you to track all the requests sent and their results. Each request is recorded with the following information:
- Date and time of execution: Allows you to identify when the request was sent.
- Type:
- Synchronous: The request is sent, and INO cx waits for the response before proceeding with the next actions. This means the result is available immediately after the request is sent.
- Asynchronous: The request is sent, but INO cx does not pause execution while waiting for the response. The API may respond later, and the results will be processed once received.
- HTTP method used: GET, POST, etc.
- Called URL: Indicates the address the request was sent to.
- HTTP response code: Allows you to know if the request was successful (200 OK) or encountered an error (400 Bad Request, 500 Internal Server Error, etc.).
- Response details (blue double arrow): Shows the data returned by the API.
The history is particularly useful for understanding the behavior of web services and adjusting their configuration if needed.
Note: when a web service fails, an HTTP response code is returned. Here are some common errors and how to manage them:
- 400 bad request: The sent request is malformed. Check the syntax of the request and ensure that all required parameters are present.
- 401 unauthorized: Authentication failed. Check your credentials or authentication token.
- 404 not found: The API URL is incorrect. Check the target URL and make sure it’s valid.
- 500 internal server error: The external API encountered an internal error. Check the error history for more details and contact the API provider if necessary.
Execution and usage
Once configured, a web service can be tested using the gear icon inside the web service.
It can then be used across several modules in INO cx on the Banner (smart routings, workflows, custom buttons).