5 Things to Know when Starting a REST Client Development Project
Updated: Jan 18, 2023
If you are a regular visitor of our TIC blog site or if you have attended one of my TIC REST Webinars, you already know about many of the benefits that REST can bring to your NonStop applications. The purpose of this blog is to provide a practical guide to prepare you for a REST Client programming project. These five easy steps can help you get started off on the right foot and get the project done more efficiently.
Let’s say that you are interested in developing a NonStop application to access a REST web service. This REST web service could be something that runs on a Windows or Linux server within your enterprise, or in a Cloud Service on the Internet. How should you proceed?
1. Ask the REST web service provider for the Swagger File
Swagger is to REST what WSDL is to SOAP. It is a JSON (usually, sometimes it can be in YAML) document that contains all the necessary information on how to consume the REST API. Having the Swagger file will save you a lot of time and effort, because it is basically a “contract” between the client and the server. Read more about Swagger.
Swagger Example
If you use the LightWave Client product, you can just IMPORT the Swagger file in the browser based Console, and the API definitions will be done automatically!
2. So, they gave you a Swagger file. What is next? Validate the Swagger file.
I know it is kind of hard to believe, but quite often, the Swagger file may not be correct! If that's the case, the next immediate step is to have it validated. This website is effective and easy to use. If the Swagger fails validation, you will need to send it back to the REST service developer and point out the errors to them. Another nice feature this website offers is that it can convert a Swagger file from YAML to JSON format.
Example of a Swagger file with errors
LightWave Client Console can also detect errors in an imported Swagger file.
3. “What Swagger file? We don’t have one.” What now?
Don’t be surprised if some web service providers do not provide a Swagger file, either because they don’t want to or they don’t know how. What you will need to do then is to construct the definitions manually. This can only be done by asking the REST web service provider for the needed information (the ones that are available in a Swagger file), such as:
Base-URL of the web service (e.g. http://www.mycompany.com/rest/accounts)
What are the different operations? (e.g. “add account”, “update account”, etc.)
For each method/operation, specify
Path (e.g. /add, /update, etc.)
Method (e.g. GET, POST, DELETE)
Data content (JSON, XML, Blob, etc.)
Request and Response layout – including data type, size, limits, etc.
As you can see, all this work would be eliminated if you have a Swagger file. Better yet, you wouldn’t have to worry about manual errors. Also, make sure you consider some of the differences between NonStop and the external platforms in the definitions, e.g. data type (what is a “long”) and maximum string size (“unbounded” is not allowed on NonStop).
4. Ask for sample Request and Response messages.
This will allow you to use the sample messages to verify the definitions they have provided. Don’t be surprised to find discrepancies between the sample and the information they sent you. An example of what a sample Request could look like:
The LightWave Client has a nice built-in feature that allows you to use an example of Request and Response to build the API data definitions. It is the next best thing to having the Swagger file because it eliminates some of the manual entry effort.
5. Use a desktop tool to test out the REST web service.
There are many great tools available for free that you should use to test out the web service. It will allow you to verify the definitions and test out all the scenarios (especially error conditions) before you start coding. In addition, this can be used for debugging during development phase, or volume testing (for response time) during QA phase. The two tools that I recommend are SOAPUI (don’t let the name fool you; it does both SOAP and REST) and POSTMAN (REST only).
SOAPUI
POSTMAN
The built-in diagnostic log tool in LightWave Client will be a great help in your debugging effort.
If you follow these basic steps, you will be well prepared to tackle any REST API project effectively. Also, make sure you visit our website to find out how LightWave Client can make your programming job so much easier on the NonStop.
Read more REST blogs:
Feedback Please
Do you find this tutorial blog helpful? Let us know what you think, and how we can make it even better. Don’t forget, you can subscribe to our blogs to get automatic email notification when a new blog is available.
Phil Ly is the president and founder of TIC Software, a New York-based company specializing in software and services that integrate NonStop with the latest technologies, including Web Services, .NET and Java. Prior to founding TIC in 1983, Phil worked for Tandem Computer in technical support and software development.