Search our Wiki
REST Web Service
The Connection REST Web Service is used to connect and transfer data to/from REST-based Web Services.
Some additional setup might be needed in Rapidi to use a REST-based Web Service, so please contact us to plan how to use this.
Some REST Web Services support the discovery of all their functionality using a JSON Schema (see http://json-schema.org) - this connector also supports this - you enter the URL for the JSON schema for the REST WebService in the Metadata URL field and press Read Design.
We have also added support to Read Design from Swagger 2.0-based metadata.
REST Web Services can be developed in many different ways as there is no real standard for REST and JSON-based services yet. To know more about which specific REST Web Services we have already tested and used with other clients, please contact us and tell us what service you plan to use and for what.
Note: If you need to set up a Storyblok connection, please follow the steps from this page.
Additional Installation
You might need to provide information about the REST Web Service endpoints - the preferred way is to provide this in JSON Schema format (see the Metadata URL below) - otherwise please contact us.
Additional installation (RapidiConnector - only for local installations or if you control the hosting environment)
Installing the RapidiConnector
Please Note: The REST Connection is by default created with an attached RapidiConnector. If you don't need the RapidiConnector - if you want Rapidi to connect directly to your REST endpoint - you need to delete the RapidiConnector from the Connection (click the trashcan icon (Delete RapidiConnector) all the way to the right on the RapidiConnector header).
Configuration
The fields of the REST Web Service Connection Card are described as follows:
- Code: A unique automatically generated code for the connection.
- Description: Enter a text describing the Connection.
-
Authentication Type: Choose how to authenticate with your Rest Web Service system.
- none: No authentication.
- NTLM (windows local network): To use NTLM you need to install the RapidiConnector and specify UserID, Password, and Domain below. The system that you connect to should be on the same local network as the RapidiConnector.
- Basic (UserID + Password): This option will use the UserID and Password provided to form an HTTP Authorization header with Basic authentication (UserID + Password base64 encoded - it will optionally also add the Account if specified).
- Token (from Password field): This option will use the value provided in the Password field as a Token to form an HTTP Authorization header with Token token="<token value from password field>".
- Token request: This option will use the UserID and Password provided to send a login (token) request to the service. If successful, the service should return a JWT Token to form an HTTP Authorization header with Bearer <token value>. This is the Authentication used for the MyRapidi REST API (REST_API).
- OAuth2 (Azure AD): This option will perform an OAuth2 authentication with Azure Active Directory. Specify UserID (ApplicationID), Password (Key), Domain (Tenant ID), and STSEndpoint/URN (the Azure AD Resource) below. If you want to do OAuth2 Authentication with a different directory (Not Microsoft Azure AD), then please contact us.
- Server Connect: Specify the URL to the REST Web Service - like: https://api.publit.com/publishing/v2.0/invoices
- Account: Some REST Web Services require an Account to be entered (optional) - only used with Basic Authentication.
- User ID: Here you specify the UserID to be used to connect to the REST Web Service.
- Password: Here you specify the Password corresponding to the above user id. For token-based access to a REST Web Service, you enter the Token here and leave the UserID field empty.
- Domain: The Domain for Authentication. For OAuth2, this is the Tenant ID of your Azure AD. For NTLM this is the network domain (e.g. WORKGROUP).
- Metadata URL: If the REST WebService supports JSON Schema (or swagger 2.0), then enter the full URL to the JSON schema in this field - like: https://api.myrapidi.com/api/v2/schema
- Use SSL: Check this field if the connection should be using SSL (HTTPS) - we recommend always using SSL.
Pagination - using limit and offset
The REST connector supports reading data in a paginated way - e.g. using "limit" and "offset" parameters to read a limited number of records on each GET request.
The feature is automatically enabled when you add a Source Filter with a value like "limit=20" to your transfer. You can of course use a different limit than 20.
When Rapidi detects that you have "limit=xxx" as Source Filter, then it automatically adds the parameter "offset=yyy" to each request, until no more data is found. The yyy is calculated for each request - for example, if the limit is 20, then "offset=0" for the first request, "offset=20" for the next request, and "offset=40" for the third request, and so on (until no more data is returned or until fewer records than the number set in "limit" are returned).
When Rapidi detects that you have "limit=xxx" as Source Filter, then it automatically adds the parameter "offset=yyy" to each request, until no more data is found. The yyy is calculated for each request - for example, if the limit is 20, then "offset=0" for the first request, "offset=20" for the next request, and "offset=40" for the third request, and so on (until no more data is returned or until fewer records than the number set in "limit" are returned).
Here is an example of a full URL: https://api.myrapidi.com/api/v2/service/233/logs?limit=20&offset=60
This feature is available from version 4.1.03k
Source Control
The fieldname entered in "source Control" on the Transfer, is used together with the RTI value to create a URL parameter for the GET request as follows: <sourcecontrol fieldname>=<rti value>&<sourcecontrol fieldname>_args=greater (or greater_equal if the sourcecontrol field is a datetime field).
For example, if having "id" in the "Source Control" field on the Transfer and the current RTI value for this Transfer (and source and destination) is 789, then the following URL parameter would be added to the base URL: "id=789&id_args=greater"
Another example using a datetime field called "log_datetime" and with an RTI value corresponding to "2020-05-23 13:27:55", then the following URL parameter would be added to the base url: "log_datetime=2020-05-23T13:27:55Z&log_datetime_args=greater_equal"
This feature is available from version 4.1.03k
Copy, Test, Activate Changes, and Read Design
Copy Connection
Connection Test
Activate Changes
Read Design