REST Connector
The REST Connector extracts data from applications using REST APIs, such as Jenkins or Git, for use in Birst. It supports many of the common use cases of RESTful APIs.
Support includes:
- Authentications
- None
- Basic
- OAuth 2.0 None, Authorization Code, Implicit Grant, Client Credentials, Resource Owner
- Request Methods
- GET
- POST x-www-form-urlencoded or raw
- Request/Response Formats
- JSON
- XML
- Pagination Types
- Paging Parameter
- Offset Parameter
- Cursor Pagination
- Fully Baked URL/Partial Resource URL
- Multiple calls (multiple endpoints)
- HTTP requests using a self-signed certificate
Implementation and Usage Notes
To use the REST Connector, be familiar with HTTP requests, endpoints, resources, and URL parameters. Consult the REST API documentation for the application to determine the URLs that will return the data you require.
Application Connectors access cloud-based applications, not on-premise applications. Birst must be able to connect to the application using a URL.
For general usage notes see Connect to Cloud Applications Using Application Connectors.
Multiple Endpoints Note
When using multiple endpoints, one or more of the endpoints generated could be invalid and by default the extraction would fail. To avoid this, in the Build Request tab set the Action on Failure to Ignore so that whenever such endpoints are encountered, the error is ignored and the next endpoint is considered for extraction.
Request Throttling and "429 - Too Many Requests"
If the API has implemented request throttling as part of usage governance, it may return an HTTP Error "429 - Too Many Requests" and a wait time (Retry-After response header) after which the request can be retried. To handle this, the REST Connector retries the request after the wait time. If this error re-occurs, the connector fails the extraction after 5 retries, if the Action on Failure property is set to Retry. If the property is set to Ignore, the connector will skip this request. If the API does not return a wait time, the connector uses a default wait time of 5 seconds as the retry interval. The default retry interval and number of retries are configurable and can be set in the RESTParameters.txt file in RestConector.
JSON Note
Because JSON requests are different than other methods used by application connectors, and due to the limits on extraction fields, you may need to create multiple extraction objects for different resources and/or increment through the rows returned. See the suggestions at Extracting Data Using REST.
Eloqua Note
The Eloqua REST API give a "500 Internal Server Error" intermittently while extracting data. However on retrying the same request, it is successful and returns the required data. When using the Eloqua REST API, in the Build Request tab set the Action on Failure to Retry so that the request is retried when an error is encountered.
URL Conventions
Different Web Services use different values for the URLs that return data from the applications. The REST Connector requires the following syntax for URLs:
HTTP | HTTPS://<ServiceEndpoint>/<ResourcePath>?<QueryOptions>
Where:
- The protocol is either HTTP or HTTPS.
- ServiceEndpoint: Root URL of the Web Service used to retrieve data.
- ResourcePath: Path that identifies particular data to be returned.
- QueryOption: URL parameters consisting of name/value pairs separated by ampersands (&).
See the documentation for the particular Web Service to determine the values to use.
Example URLs
See the example URLs below. You will enter different parts of the URL into the UI. See the examples in Extracting Data Using REST.
https://community.jivesoftware.com/api/core/v3/people?count=100&startIndex=1
http://services.odata.org/V4/Northwind/Northwind.svc/Customers
http://jenkins.birst.cc/api/json?depth=1