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
Object oManualSimpleAPI is a cszWebAPIController
Set psPath to "api/v1/manualsimple"
Set psVerbs to "*"
End_Object
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
// get method returns data as json
Procedure ManualGet
Integer hoJson
Get Create (RefClass(cJsonObject)) to hoJson
Send InitializeJsonType of hoJson jsonTypeObject
Send SetMemberValue to hoJson "timestamp" jsonTypeString (ConvertToClient(typeDateTime, CurrentDateTime()))
Send SetMemberValue to hoJson "message" jsonTypeString "Hello World"
Send OutputJson hoJson
Send Destroy to hoJson
End_Procedure
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
// register path with method Send RegisterPath "GET" "" (RefProc(ManualGet)) Set pbPathScalar to True Set psPathSummary to "Manual API function"
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
{
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
// Procedure OnDefineModels Send BeginModel "manual" Send AddModelColumn 0 0 False jsonTypeString DF_ASCII "timeStamp" False False Send AddModelColumn 0 0 False jsonTypeString DF_ASCII "message" False False Send EndModel End_Procedure
then we need to assign the model to the route as well
// Send RegisterPath "GET" "" (RefProc(ManualGet)) Send AddPathresponse 200 "successful" "application/json" True "manual" Set pbPathScalar to True Set psPathSummary to "Manual API function"
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.
