What questions should I be asking about my API?

Testing is a crucial part of any software lifecycle, however when working with APIs that extend your existing z Systems investment there are some key differentiators that you need to consider when developing and implementing your API strategy.

I’m a strong believer in applying the right thinking to your testing as soon as possible and not allowing conventional test phases preclude you from applying ‘system-test’ techniques as soon as possible. It is much more important to understand the key risks and complications in delivering your new functionality and apply the test techniques that best mitigate those risks as early as possible during development. During this post I will dis-cuss the following 3 questions:

1. Is this the right API?
2. Does my API scale?
3. Does my API integrate?

Is this the right API?

The first test that is often applied is the ‘golden path’. A simple single request is made into the system to prove that the request can be processed correctly and data returned to the client. I would stress however that this shouldn’t be the first test that you run. If your API isn’t consumable by your client or provides useful data then it doesn’t matter if it works or not.

Consider your use of path parameters and JSON data formats carefully. Some questions that you can ask:

1. Can you infer the behavior of the service from the URL path? A good API should be to some extent self-documenting.
2. Do all the HTTP verbs make sense against the path of the API? If some verbs are not going to be used as part of the implementation then make a note of them now so that you can test them later. Or at least ensure that the swagger documentation for the API makes it clear that they are not supported
3. Is the format of the JSON in the response and request (if applicable) HTTP body easily consumable? Although JSON is easy to parse in most languages, a badly designed JSON datagram can be confusing and require a lot of effort to understand programmatically

Ensure that the API abstracts away concepts that might not be familiar to a non z Systems developer. RESP and RESP2 codes should be wrapped into more generic error messages or HTTP codes. Eye-catcher variables and variables only used in the request / response message should be omitted where possible.

Fortunately, a lot of this testing can be done very cheaply. Free tools such as http://www.jsoneditoronline.org allow you to experiment with JSON data formats. If in any doubt then a form of a/b testing can be employed to see which API your clients prefer.

Once you have the ‘right’ API designed and implemented then you can try that golden path test. Again free tools can parse your swagger document describing your new API and provide simple HTML forms to call your new service, such as http://editor.swagger.io/#/ By doing this small piece of testing first you will know that the API you are building is the right API as well as a correct API

Does my API scale?

So you have the right API implemented but does it scale sufficiently to meet your expected client demand? Within IBM we spend a lot of effort ensuring the scalability and reliability of our runtime products. However you need to ensure that the application you are extending as an API does not have any constraints that prevent the API from running well under load. Being a restful paradigm should mean that problems like affinities within a workload managed system should not be an issue. However system constraints such as max tasks, transaction classes or use of temporary storage could be a potential issue.

While you are still developing parts of your API it might not be possible to conduct a full production-like load test. However, you can still gain a lot of early value by artificially constraining the system and running it under a smaller load while still exercising ‘at load’ conditions. Obviously the set of constraints will vary depending on the application and runtime used. However you might want to consider constraints like:

• Maximum number of tasks in system
• Amount of application storage available
• Amount of test ‘items’ in application database

Open source tools such as Apache JMeter http://jmeter.apache.org can be used to quickly develop a basic workload against your API. Once developed, it can then be executed in a headless mode on a different system (even on the mainframe) to increase the throughput. While your workload is running, application and system monitoring tools can be used to understand:

• Memory leaks
• Orphaned threads being left in system
• Application data not cleaned up during execution

While developing a workload it is always a good idea to introduce a percentage of tasks into the load that will error on purpose. Introducing errors into a workload and therefore executing error paths while the system is under load is usually a good way of finding defects.

Does my API integrate?

When an existing application is being extended as an API, you also have to consider the impact that the new workload will have on your existing application and operational scenarios. How well will your new API integrate with the rest of your system?

The first difference is that your new API will bring new workload into your system. How will this new workload affect your existing workload profile? Will the new workload require you to consider increasing your capacity for peak times? Is it possible for the new workload to flood the system and cause SLA failures in your existing applications?

Do you want to use alias transactions to logically separate the new API workload from your existing workload? This could be important if you need to throttle either workload. The ability to distinguish between your API work-load and your existing workload is important also for debug and service purposes.

Summary

Extending your application to be called from an API is going to be a simple process. However there are some important points that you need to consider. By spending a bit of time understanding the consumption of the API, its ability to scale and its integration points with your existing z System applications you can avoid some of the most common pitfalls.