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

See Shopify 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

See Mailchimp Authentication

Request Throttling

Mailchimp does not throttle unless there is a 10 simultaneous connections.

https://developer.mailchimp.com/documentation/mailchimp/guides/get-started-with-mailchimp-api-3/#throttling

Leave the throttle type set to None.

Paging

Paging is described within the Parameters section section on the getting started page.

https://developer.mailchimp.com/documentation/mailchimp/guides/get-started-with-mailchimp-api-3/#parameters

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

See JIRA 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.

https://community.atlassian.com/t5/Answers-Developer-Questions/How-to-do-pagination-on-JIRA-Rest-api/qaq-p/516052

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