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
Shopify does not provide a specific page for describing how request paging is handled. Instead there are scattered (historical) forum posts describing paging.
https://community.shopify.com/c/Shopify-APIs-SDKs/How-the-pagination-works-in-shopify-product-API/m-p/269630
This can be combined with the limit on parameter described on the Orders API page.
https://help.shopify.com/en/api/reference/orders/order#index
Both these links indicate that paging is implemented by passing the page and limit parameters in the URL.
- Paging Type
- URL
- Paging Start At
- 1
- Paging Path / Parameter Name
- page
- We do not use the limit parameter. If you wish to use the maximum limit of 250 pass the value in the URL specified on the Reader.
- Paging Increment By
- 1
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
