To confirm if an API End Point available and suitable for the integration scenario you are working with, you should follow these steps:

1. Familiarize yourself with the API’s specifications and requirements.
2. Define test cases and test data that covers a range of scenarios for the API, such as error handling, edge cases, and normal use cases.
3. Use a testing tool or programmatically send requests to the API and check the responses against the expected results.
4. Monitor the API’s performance, such as response times and error rates, to ensure that it meets the required standards.
5. Repeat the testing process in different environments and at different loads to ensure the API’s stability and scalability.
6. Address any issues or bugs found in the testing process with the API provider and repeat the testing process until the API is confirmed fit for purpose.
7. Document the testing process and results for future reference and maintenance.

Commands to use to test End Points

The following table defines the commands in Linux which can be used to check connectivity for each of the types of end points.

A stub is an interface that simulates the actual object and returns pre-defined and expected Responses irrespective of input.

A mock is an interface with a bit more ‘intelligence’ in that you can configure you mock services to return results based on what you send.

Benefits

• Speedy delivery
• Focused and reliable testing
• The ability o test components accurately in particular contexts
• Obtain feedback quickly from a manual or automated test

When to use a stubs & mocks?

If we are developing the back end of a minor application with a third-party to interact with an API, we can implement an interface that can disconnect us from the third-party library. Eventually, that interface will act as a stub and yield hard-coded values. Conclusively, we can use values in unit tests.

When initiating any integration project the first step is to build a solid understanding of context and scope. The following steps provide guidance as to where to best focus your efforts.

List the Integration Use Cases: (also referred to as Transactions) that are in scope e.g. Balance Enquiry, Withdrawal, Airtime Purchase etc. This can take the form of a simple descriptive list.

List the End Points: (these are the business systems involved in all in scope transactions) and identify which are Initiating Systems (e.g. Web Channel / ATM System / Back Office UI etc.), Receiving Systems (e.g. Core Bank System / ERP / Database / Message Queue / Airtime Platform etc.). Some End Points and be involved in certain transactions as Initiating Systems, and in others as Receiving Systems.

For each End Point gather information relevant to your integration – the system type (e.g. Oracle DB / Rabbit Message Queue), if an API is available the Protocol (e.g. REST / SOAP / TCP / ISO8583 etc. DB Connector or ISO), the system Name and Version, the API Version etc.

Create an Integration Context Diagram: This graphical representation provides an efficient means of building a quick understanding of End Points involved, how they inter-connect, where they are located and so on. Start simple and elaborate as you gather information about the Integration project you’re working on. You can also start to identify the specific GLU.Engines need, since GLU.Engines can be connected to each other, it often makes sense to have more fine-grained GLU.Engines so they can be updated and evolved independently to minimise downtime in event of any changes being needed. GLU.Engines can also be monolithic, servicing connections to multiple Endpoints. See the example adjacent.

Create Sequence Diagrams: To align the understanding of the Use Cases, we recommending documenting them as UML Sequence Diagrams (you can use tools such as MS Visio or Draw.io). Typically to start you can focus on just the ‘positive’ or ‘happy day’ scenarios – see simple example below. Later, one should elaborate these to include the ‘failure’ scenarios. You might be able to source existing sequence diagrams if such exist. Whiteboard sessions are a good way to talk through the flows of each transaction.

Gather End Point Connection and API Specification Documents: Based on the list of End Points, collect all available API Specifications. Note that API Specs are notoriously inaccurate so some digging may be needed, always ask if the version you find is the latest (check the change control in the doc to see when it was last updated – docs that have not changed in 12 to 18 months or more are may well be outdated). If you have any SOAP API End Points in your scope, get hold of the associated WSDL files.

Gather End Point Connection and API Authentication and Authorisation details: Based on the list of End Points, document the authentication and authorisation details, SSL certificates, encryption methods used etc. Typically different credentials will be required for Test vs. Production and it may be that Production credentials may only be shared when required.

Gather Host Details: The Host URL or IP Address and Port details for each End Point for Testing and any subsequent stages in your Integration Lifecycle are needed.

Establish Test End Point access: This enables you to directly send test messages at the Test End Points and in-so-doing to gain a first hand understanding of each API. This step can take time as security sensitivities may necessitate VPNs to be put in place or special access controls to be used. This access is critical to the Integration Lifecycle so needs to be established as soon as possible. Utilise tools such as Postman to perform this step, moving from testing directly in Postman to creating a cURL command from Postman and applying this from the server which the GLU.Engine will be run from (by doing this you will test the network and port configuration too). Please refer to Test End Points for details on approach and tools.

Gather any existing Test Cases or Test Packs: These can be useful as they may highlight some of the failure scenarios that have been already identified. If automated test pack collections such as one might use with tools such as Postman or SOAP UI are available, these will help with your own test pack creation. GLU’s preferred test tool is Postman. Sometimes incumbent IT teams, suppliers or partners will have a Quality Assurance or Test Team or person. Identify who these people are and ask them for any existing Test Cases they may have. Use any available existing test cases to start to build up the test pack for your integration use case covering both positive and negative scenarios.

Gather End Point Sample Request/Response messages: Since APIs are often inaccurate, the fastest way to understand how an API behaves is to get working sample messages for each step of each in scope Use Case. This can sometimes be challenging but is worth the effort, some approaches to consider: If systems you are integrating to already exist, typically someone would have tested them, if so they may be able to provide such samples, leverage any inputs you might have gathered from your efforts to gather existing Test Packs. If you have established Test End Point access (see above) that often will give you the best mechanism of generating these sample messages. Detailed System Logs will often also trap the inbound / outbound message payloads. These are often considered ‘sensitive’ so may require obfuscation of sensitive data they may contain. This approach can also get complicated as logs from each End Point would be needed creating a potentially heavy workload to process them all. Regardless of how you gather your sample messages, having them will help to accelerate you integration configuration.

Provision VMs for GLU.Engines: for each stage of the Integration Lifecycle. See the GLU.Engine Server recommended specifications.

Define the GLU Logfile Requirements: Not always critical for initial PoC’s but almost always essential as a pre-requisite for integrations prior to ‘go live’. See the GLU Logfile page as a start but define any Client specific dashboards as needed.

Define GLU System Metrics Dashboard Requirements: Clients should use their existing Metric Analytics and Dashboard tools to monitor their GLU.Engines. The full spectrum of JMX Metric’s is available to be consumed by any compatible Monitoring tool. Click here for more on the JMX Metrics.

Useful Tools

This Template provides a succinct basis against which an Integration Project can be executed … GLU – Project Definition Document – Template – v1.0

There are a number of tools that one can use for various purposes to assist with streamlining integration projects. Below are a few such tools that the GLU team often use. It is important to understand the context of any integration, to do so, drawing tools such as below can be used to build up Context Diagrams that show the initiating system/s and the various receiving systems involved in your integration project. Try to capture as much detail as possible in this visual artefacts.

• https://app.diagrams.net/ – for building up Context Diagrams – a free and very powerful alternative to Microsoft Visio
• https://mermaid-js.github.io/mermaid-live-editor/ – a free and powerful tool to assemble Sequence Diagrams

In order to Test your GLU.Engines you need the ability to send messages and see responses. We use Postman widely for this purpose. Additionally you’ll need to interrogate the GLU.Engine logs, this can be done directly or using a lookset like the Elastic Stack.

• https://www.postman.com/ – For Testing your GLU.Engines
• https://www.elastic.co/elastic-stack – for Log Analytics – Elasticsearch, Kibana, Beats, and Logstash (also known as the ELK Stack), allows one to search, analyze, and visualize GLU.Engine logs it in real time.
• https://hawt.io/ – a free tool to visualise your GLU.Engine JMX Metrics

Other tools that may be of use:

• https://www.docker.com/ – If your are using Docker Containers to run you GLU.Engines

The Integration Lifecycle

The Integration Lifecycle for your project may vary from that outlined below depending on specific constraints you may encounter in your project. Use this as a guide.

Probe Test Phase:
Once you have access to the Test End Points, you can commence probe testing each End Point. This provides you with an understanding of how the actual End Points behave. Tests you fire (e.g. from Postman) may be based on existing test cases you’ve managed to source, or from test cases you have created in your test tool (Postman) based on your understanding of the sample Request/Response messages you’ve sourced (first prize!) or failing that based on just the API Specs.

Lab Test Phase:

1. Build Stubs: Based on your Probe Test results, using the sample Request/Response messages you are able to configure (or build) Stubs / Mock Services for each End Point. These could be stand-alone GLU.Engines that are provisioned to behave as Stubs / Mock services or they can be embedded within the integration GLU.Engine configuration. Initially just focus on the ‘happy day’ Response scenarios to get those working, the ‘failure’ scenarios can be added to your stubs and Lab Tests thereafter.
2. Build Test Packs: For each Use Case, build the test cases in your Test tool (e.g. Postman).

Incrementally Configure and Build your GLU.Engine:

1. Configuration: Break the configuration of each Use Case into logical segments and test each segment as you go.
2. Lab Tests: Build your Lab Test GLU.Engines for testing from the Test GLU VM or Server as you go. Depending on your security policies it is also possible build initial Lab Test GLU.Engines for ‘localhost’ so you can download and test directly from your laptop or PC providing you have access from there to your Stubs. This may have security implications so should be pre-authorised by relevant parties.
3. Start combining working segments to build up the full Use Case.
4. Logfile Analytics: At this phase, one should also lab test the Logfile Analytics (if in scope).
5. Metrics Dashboard: At this phase, one should also lab test the Metrics Dashboard (if in scope).

Integration Test Phase:

Build a GLU.Engine for the System Integration Test (SIT) Environment. You’ll need the host details for all the Test End Points as well as for the VM you’ll be running your GLU.Engine from. Execute your Test Pack for all Use Cases starting with the ‘happy day’ tests and then expanding into the ‘failure’ scenario’s.

UAT Phase:

Optional, depends on Clients process.

Pre-Production Phase:

Optional, depends on Clients process.

Production:

The ultimate objective, your GLU.Engines will no longer be tagged as ‘SNAPSHOT’, they will be tagged as version specific ‘RELEASE’.

A good API design makes the API easy to consume by the app developer. Below are a set of design best practices that have enabled many API designers with SOAP design experience to build the right set of easy-to-consume RESTful APIs. Using a data-centric model APIs should focus on the underlying entities/resources they expose, rather than a set of functions that manipulate those entities. In other words, the URLs should have nouns, not verbs.

For example, a collection of cars could have a URL https://cartracker.com/cars. And, individual cars would each have a unique URL like http://cartracker.com/cars/9672376. With this approach, you can retrieve the details of the car using the GET method, delete the car using the DELETE method, and modify properties of the car using the PATCH or PUT methods.

By contrast, in a function-oriented API, there is much more variability, and much more detail a developer has to learn. And there is no clear structure or pattern you can use to help them with the next API.

Building simple JSON

Due to its simplicity, JavaScript Object Notation (JSON) has become the de facto standard for web APIs. When JSON is used well, it is simple and intuitive. If your JSON doesn’t look as straightforward as the example below, you may be doing something wrong.

{

“kind”: “Car”
“name”: “BMW”,
“Color”: “Silver”,
...

}

Your JSON API will be simpler and easier to understand if you stick to the principle that the names in your JSON are always property names, and the JSON objects always correspond to entities in your API’s data model.

Expressing relationships as links

If your web APIs do not include links today, a first step is simply to add some links without making other changes, like this:

{ “id”: “12378”, “kind”: “Car” “type”: “BMW”, “Colour”: “Silver”, “ownerID”: “9876599”, “ownerLink”: “https://cartracker.com/persons/9876599” }

Using links makes it easier for app developers to consume resources, with less to learn and no need to hunt for documentation. Moreover, links can be plugged into templates to produce the right URL.

Designing URLs

A good way to make APIs human-friendly involves the creation of entity URLs that have the entity type in them when fetching a specific resource. Thus, instead of https://cartracker.com/RTRX4545666, it is more desirable to have https://cartracker.com/cars/4545666.

Also, it is not recommended to code a hierarchy of entities into an URL. Hierarchies are not as stable as they might seem; encoding them in your URLs could prevent you from reorganizing your hierarchies in the future.

For query URLs, it is recommended to use the format:
https://cartracker.com/persons/{personId}/cars rather than 
https://cartracker.com/search?type=Car&owner={personId}

Many app developer prefer the first format because it is more readable, more intuitive, and easier for API developers to implement.