RESTful Web Client API (v2) Reference

RESTful Engine Clients – version 2

This page is for the RESTful client API version 2 (v2). This is first available in the RESTful engine 20.1. Previous versions only support API version 1 (v1).

The RESTful engine 20.1 and later supports both v1 and v2. It is strongly recommended that you use the v2 API, which is fully asynchronous.

Versioning

There are four versions when it comes to the RESTful engine & clients. First & second are the RESTful and .Net Engine server versions. These are usually the same and are in the form of 20.1.0.127. This tells you what engine you must use to run your request.

Third & fourth is the API version. This is the version for the requests sent by the clients and received by the RESTful server. And then the response returned. Both the server and client have this version and it is in the form of 2.1.0. The first two digits must match for error free communication (i.e. a client of 2.2 will have problems talking to a server of 2.1). The third digit is a change that does not materially affect the defined communication API.

Requests

The engine can have calls to request three things: generate a document, get a template’s metrics, and get a template’s tag tree (there’s also a getVersion call).

For all three requests they break down into the following steps:

  1. Submit the request.
  2. Get the status to see if it is complete (you can also send a callback in the initial request).
  3. Get the generated document/metrics/tag tree. Or if there was an error, get the error.
  4. Delete the generated document/metrics/tag tree from the server.


Windward Supported Clients

Windward supports the following clients. These clients are supported by our support team and we will fix any bugs discovered in them. We strongly recommend you use these clients.


.Net Standard 2.0 Client

The .Net client works with C#, VB.Net, and any other .Net language. It is .Net Standard 2.0; therefore, it works on .Net Framework 4.6.1 and later, as well as .Net Core 3.1 and later.

It uses the .Net async/await constructs on everything. So, all calls in the API are asynchronous.

We provide the following resources:

Java 1.8 Client

The Java client works with Java 1.8 and later.

Because there are no asynchronous web client classes, the individual calls in the Java client are synchronous. But the REST server is still asynchronousso you still have the individual calls over the course of a request.

We provide the following resources:

To pull the jar from maven, add the following to your pom.xml file:

JavaScript Client

The JavaScript client uses the async node-fetch library to make requests. So all calls in the API are asynchronous.

We provide the following resources:

Python Client:

The python client uses a Requests library which processes all API call asynchronously. While the requests are being handled async on the backend, all client method calls will be synchronous in nature.


We provide the following resources:

Other clients

Coming soon:

  • PHP



Swagger

Windward does not support any clients created using Swagger. But we do support our Swagger yaml file and will fix any issues in that and answer questions about it.

You can get the yaml file here.

The Raw Engine API

If you wish to connect to the engine using your own client code, you can get the engine API here. This is built from the code running, so it is 100% correct for the server you are running this on (go to the same URL on your server if your server’s version is different).

If you create a client for the engine, you are welcome to make it available for others to use.

Extensions

The RESTful engine provides an extension where you can provide part of the REST server’s functionality.

IRepository

The RESTful engine stores requests and generated reports solely via this API. This API can be implemented by any system that wants to handle queueing requests and saving generated reports. For example, you can write this extension to save items to a NoSql system on your service.

If your repository is persistent across multiple REST Engine services and across servers being shut down and others spun up, then all jobs entered will be picked up by new servers when old servers go away.

To write your own repository, contact Windward for a copy of IRepository.cs and supporting files.

To use it, in your config file add:



Where filename is the DLL file containing your class, and the classname is the full classname of your repository class. If the filename is not needed, just use the classname.

Keep in mind you must build against the exact version of the RESTful engine, referencing that DLL for the IRepository class you are extending.

0 Comments

Add your comment

E-Mail me when someone replies to this comment