Webservice Behaviour
This page shows you how to setup webservice behaviours for the different services.
As noted in the introduction a lot of the information is found from both the official API document for the REST API and forum posts where clarification is needed.
Shopify
Most resources are located in the following resources.
https://help.shopify.com/en/api/getting-started
BASE URL
The Base URL is described in the section of the Getting Started Guide.
https://help.shopify.com/en/api/getting-started/making-your-first-request#making-your-first-request
It indicates a URL which includes the username and password. This is confusing since IMan will provide the username and password via the Authentication.
https://{username}:{password}@{shop}.myshopify.com/admin/api/{api-version}/{resource}.json
The url needs to have the username and password be stripped out leaving:
https://{shop}.myshopify.com/admin/api/{api-version}
The key here is the {shop} part of the url which is your Shopify shop site.
In our example we have https://realisable-test.myshopify.com/ (we've dropped the admin/api/{version} as we'll add those in the various requests).
Authentication
Request Throttling
Throttling information is taken from the following note on the REST API.
https://help.shopify.com/en/api/reference/rest-admin-api-rate-limits
- Type
- Leaky Bucket
- Http Status Code
- 429
- Requests Per Second
- 2 or 4
- This is dependent on whether being connected to Shopify or Shopify Plus.
Paging
Starting in the end of 2019 Shopify introduced a new means for paging data, based on a link with the HTTP header which points to the next page of data.
https://www.shopify.com/partners/blog/relative-pagination
A more concrete example of the new paging by Shopify can be found here.
https://shopify.dev/tutorials/make-paginated-requests-to-rest-admin-api
This style of paging, is certainly complicated, but version 4.2 added inbuilt functionality for handling this style.
- Paging Type
- Header Link
Trace
Enabling tracing will write to the trace file for the particular service. The trace file is written to the \IMan\Debug directory where the file is in the form WSTRACE-<BEHAVIOUSID>.log.
When first integrating with a service we recommend enabling the trace as this will help you understand the calls being made by IMan and any responses being returned from the server.
The following examples will reference the trace.
Mailchimp
The main reference for the Mailchimp REST API can be found on their Getting Starting guide. This page describes everything needed for setup.
https://developer.mailchimp.com/documentation/mailchimp/guides/get-started-with-mailchimp-api-3
Authentication
Request Throttling
Mailchimp does not throttle unless there is a 10 simultaneous connections.
Leave the throttle type set to None.
Paging
Paging is described within the Parameters section section on the getting started page.
The page provides an example of pagination indicating it's url based, using the 'offset' parameter starting at 0. The offset should be incremented by 10 (or more) using the 'count' parameter for each page.
- Paging Type
- URL
- Paging Start At
- 0
- Paging Path / Parameter Name
- offset
- Paging Increment By
- 10
- This can be increased.
- Paging Increment / Parameter Name
- count
JIRA / Atlassian
The API documentation for JIRA is aimed at developers, therefore there is some assumed knowledge. The JIRA API is REST so we need to assume the API conforms to REST standards.
https://developer.atlassian.com/cloud/jira/platform/rest/v3
Authentication
Request Throttling
No specific discussion of throttling can be found on the JIRA REST API page indicating there isn't any throttling. A forum post confirms this.
https://community.developer.atlassian.com/t/are-there-rate-limits-for-jira-cloud-apis/4317
Paging
Pagination is described explicitly on the following link.
https://developer.atlassian.com/cloud/jira/platform/rest/v3/#expansion
This however it is not clear on how paging should be handled.
The page provides an example of pagination indicating it's url based. The implementation of paging is similar to Mailchimp, where the 'startAt' parameter starting at 0. The offset is incremented by 50 using the 'maxResults' parameter for each page.
- Paging Type
- URL
- Paging Start At
- 0
- Paging Path / Parameter Name
- startAt
- Paging Increment By
- 50
- This can be increased.
- Paging Increment / Parameter Name
- maxResults
