Versions Compared

Old Version 11

changes.mady.by.user Aryn Wiebe

Saved on

compared with

New Version Current

changes.mady.by.user Aryn Wiebe

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Expand
titleModularize your web service interactions

Create separate functions for different tasks like authentication, making API requests, or specific operations/methods (e.g., createOrder APIcreateOrder). This keeps your code organized and easy to maintain.

In the Translator, these files can be organized into folders and one or more lua files, depending on the scale of operations required. Naming Conventions for Functions and Variables is an important part in creating well organized, intuitive web service operations.

For example, in the screenshot below, all files are stored in the APIclient folder.

  • apiCallAPIcall.lua is responsible for making HTTP requests and handling the responses from the API.

  • createOrderAPIcreateOrder.lua and getOrderAPIgetOrder.lua are sample API method functions that prepare the request before calling apiCall APIcall.

Image RemovedImage Added
Expand
titleUse Custom Fields to pass configurations and parameters

Avoid hardcoding configurations and parameters. Centralize configuration data in Custom Fields to make the interface adaptable and more secure.

Information such as the base URL, authentication data (clientID, client secrets, username, password, tokens, etc.), and retry logic are good candidates for custom fields! Any values set as type 'password' will be encrypted to protect sensitive custom fields.

This way, you can update configurations without modifying the core logic of your API calls.

Here we are passing createOrder() APIcreateOrder configurations and order details to use to prepare the API call:

Image RemovedImage Added
Expand
titlePass a table of parameters when calling your API

Using tables to store parameters allows you to dynamically build the data you need to send with the request. It also keeps your functions simple and , support multiple optional parameters and especially useful for long term maintenance as you can add and remove parameters without needing to modify the function call in the multiple places its called.

In this example:

  • APIcall() will prepare base parameters like the base url, authentication, etc.

  • Endpoint specific functions like APIcreateOrder() should be passed and prepare anything specific to that endpoint - e.g. query parameters,

we are passing the

  • the body of the api request, etc.

Here we have passed the specific endpoint, body and live parameter in a single table for apiCallAPIcall() to use to perform the HTTP request. We are also passing the method, to apiCallAPIcall() which is set up to make various http calls (e.g., get, put, post.)

Image RemovedImage Added
Expand
titlePreparing Prepare the body or query string parameters according to your data format

In this example, we are working with JSON data. Notice in createOrderAPIcreateOrder.lua we are first serializing the JSON as a string to prepare it for the body of the request.

Image RemovedImage Added

Depending on the API you’re working with and the type of request, there are a few functions that you may want to use to prepare the body or query string parameters:

  • For JSON: json.serialize{} to convert a Lua table to a string

  • For XML: tostring() or :S() to convert an XML node tree to a string

  • For query strings: with net.http.get() use the parameters argument to pass a table of query parameters and values to automatically append them to the URL.

Expand
titleBuild in Add resiliency to you for HTTP requests using pcall and retry logic

Make your integration more robust by handling errors and retrying calls when necessary. This is particularly useful for handling intermittent network or server issues.

Now, looking at apiCallAPIcall(), you can see pcall() and the Retry Library are used when making the net.http.* API call:

Image RemovedImage Added

See Handling HTTP ResponseResponses for the fundamentals and recommendations on how to handle responses in IguanaX.

Expand
titleDocument your functions ! for the rest of the team to use

Create Help Files (*.help) to document how your functions work and how to use them will make it easier for the rest of the team to understand and reuse your functions.

...