To start lets create a very simple manual REST service. No database involved just a simple service that returns a simple JSON object.

To do this we create a Web HTTP handler based on the cszWebAPIController class. lets call it oManualSimpleAPI

o show this we modify our main router view in App.vue as follows

This will create a simple Web API controller with the path

  • api/v1/manualsimple

all verbs are allowed

by itself this will not do anything yet. We now have to declare routes/paths and add functionality

First we want to add a simple GET method that returns a json object

In order to do this we add the following method to the controller

This method creates a json object fills it with data and returns the json data from the service.

But we also have to declare the route as follows

We register a blank path with the get verb and tell the controller to call the ManualGet method for this path.

We also tell the controller that the path has a scalar result (a single result vs a list) and we define a summary text for the route.

Now we can test this route by calling the following url for example via Postman or curl or even simply in a browser

http://localhost/szWebAPI/api/v1/manualsimple

the server should respond with a return code of 200 and the following response body

{

    “timestamp”: “2020-10-10T08:51:19.048”,
    “message”: “Hello World”
}

Now lets take a look at abother feature. The web api controller has a feature built in to document its functions using the OpenAPI specifications. These can then be viewed in swagger UI.

by default the controller is enabled to automatically produce the documentation on the root path using a url parameter called ‘openapispec’

 calling the following url on the controller

http://localhost/szWebAPI/api/v1/manualsimple?openapi=true

will create a yaml document with OpenAPI specifications describing the web service.

We can use this document for example in swagger editor to show a visual representation of our API

 

you can see in this screengrab we have a GET function for the Url /manualsimple.

It has no parameters and the response is going to send a 200 http response code.

But we do not see what type of data is returned from the service. It would be nice to know a schema for the returned data. 

All we need to do is to add some additional code to define a schema for the returned json data

To do this we add the following method to our controller

In the OnDefineModels event we create a model/schema with the name manual and add two columns to it.

then we need to assign the model to the route as well

We added the line to declare a response. The response code is 200, we added text and content type as well as a name for the schema which is “manual”

Now if we look at the documentation for our API we can see that the schema is now defined in the documentation as well

 

This will make it easier for a developer consuming our service.

This is it for this second part of the series. In the next part we will look at an API based on a database specifically the order entry sample workspace database.

Michael Salzlechner is the CEO of StarZen Technologies, Inc.

He was part of the Windows Team at Data Access Worldwide that created the DataFlex for Windows Product before joining StarZen Technologies. StarZen Technologies provides consulting services as well as custom Application development and third party products