We are attempting to use a JSON (Swagger 2.0) file to setup a REST service broker. The service instance is setup successfully but we only see 3 Service Operations.
Take one of them GET /form/v1/list - Inspecting this service operation in K2 Smart Object Explorer works as expected. We see the HTTP Response code & headers property and executing the method connects to the specified host and returns a response code
However, the method we really need is POST /form/v1/do-something and this does not generate a Service Operation. We attempted to navigate to the Object Type and create a smart object and when we execute the serialize method, it does the serialization but does not actually connect to the specified host. We even tried to add a operationID in the Swagger file but that did not help.
Again, some Object Types do have Operations listed from the Swagger but the vast majority simply have the standard Serialize, Deserialize, etc. built-in methods.
How can we get this working? How does the REST broker determine which object types are considered "executable" and hence adds a HTTP response code property and service operations? There doesn’t seem to be any difference between the GET/POST operations that work and those that do not. Seems random.
Thanks
Page 1 / 1
I would need to see your swagger definition to be sure, but I have found that K2 doesn’t know how to handle methods where the input parameters are an array. If you alter the swagger to turn the input parameter array into a definition instead, then K2 can see it.
Are you perhaps able to attach the swagger file for review?
I believe a POST will show up as a Service Operations if it’s response do not reference a definition. It may show as a method under an Object Types object if it references a definition. Or perhaps there is a syntax error that prevents it from showing up as either.
Nvm, this may apply to Get operation where you reference a definition in the response, not POST operations. POST operations may be using the path.
@tbyrne777 The input to the POST method is a JSON object with the format
{
“key1” : “value1”
,”key2”: “value2”
,”key3” : {
“key4”:”value4”
,”key5:”value5”
}
}
There are no arrays.
@TinTex Unfortunately, I am unable to share the Swagger file but I see that you are a Nintex employee so perhaps you can reach out to Nintex Support for a case I created, the case number is 00620026. There are no errors when the service instance is created so I thought this confirms that K2 is able to read, parse and validate all the paths and operations in the file. Your response is a little confusing. You are saying that a POST qualifies as a Service Operation if its response does NOT reference a definition but a Object Type qualifies it it DOES refer a definition?!
Please check the methods for one of your Object Types. I believe the POST methods are inside one of those Object Types.
I think you may be able to move that method to another Object Type by using the ‘x-k2-entityName’ or you can also create your own custom SmartObject and add the method/properties/mapping to it instead of generating them.
I checked and it is maddeningly inconsistent. Some Object types used in POST methods do generate a method, others don’t. Trial and error seems to be the only method and it is very time-consuming for a large Swagger file.
Please check the methods for one of your Object Types. I believe the POST methods are inside one of those Object Types.
I think you may be able to move that method to another Object Type by using the ‘x-k2-entityName’ or you can also create your own custom SmartObject and add the method/properties/mapping to it instead of generating them.
Sure, I can move things around but the part that I cannot control is which methods get the magic HTTP Response properties automatically attached to them which is when K2 actually sends the payload to the server and gets back a response. How can I control this? Right now, as mentioned, what I see is that K2 doesn’t even attempt to connect to the REST API server. No errors, just doesn’t even throw it over the wire.
You may need to use Fiddler on the K2 server to capture the outgoing traffic to see if K2 is sending out those POST calls. It would also tell you how the request are formatted if it is sent out.
You can try using postman on the K2 server and see if you are able to make the same post request successfully. Then compare the post request against the K2 request in Fiddler to see if there are any differences.
It looks like in your POST are you also using the ‘allOf’ schema specification which is current not supported by the REST broker.
This will definitely require some massaging of the swagger file or possibly creating some custom definitions so that you can serialize the body of your POST call to the correct format. Perhaps using RestUnited and breaking the swagger file into smaller definitions and having multiple service instances may be easier to manage/customize.
Before I undertake all this surgery, can you tell me what determines when K2 adds the HTTP response code property to a method?
My apology, I am not sure I understand the question.
Assuming that the K2 service is successful in sending the POST to your endpoint, the response that it receive from the endpoint will be evaluated as below:
What behavior are you seeing?
The behavior I am seeing is that (empirically), I am able to successfully GET/POST to the remote server only if the Object type has a HTTP Response Code property, see below. This is not a property we add manually, the K2 REST broker seems to automatically add it. My question is - When does K2 add this property?
In my example, the POST I am executing has no response body, I am just sending some data over to the server and if I get a HTTP 200 response code to indicate the operation is successful, the workflow moves on.
In all my trial-and-error so far, I have not been able to get the magic HttpResponseCode property to appear in my Object type definition and hence (I think) I am unable to actually execute the POST (I asked the API provider to check and they do not see the attempt in their logs which confirms my hypothesis that K2 is not even getting as far as making the POST call)
Any ideas?
I see, I believe the Property is automatically added to the SmartObject as a mean to return the Response Code after K2 receives a response from the REST endpoint and would just be an output value.
I assume you are able to call the SmartObject method with no error, but nothing is returned?
Some of the methods Serilize, Deserialize, etc. are system methods and does not send these request anywhere.
If the API provider don’t see anything in their logs, perhaps a firewall or something is in the way between K2 and prevents those call from hitting the API server.
From my testing, if the ‘host’ value is unresolvable for example, K2 will still send out the POST request to the specified host value in the swagger file, the response to that would be 502 DNS Lookup Failed, but because this Status was not defined in the swagger definition, an HttpReponseCode of 0 was returned in the SmartObject call.
May need Fiddler or some sort of network trace to K2 server to see if the GET/POST request was ever sent or if it was blocked, etc.
I see, I believe the Property is automatically added to the SmartObject as a mean to return the Response Code after K2 receives a response from the REST endpoint and would just be an output value.
I assume you are able to call the SmartObject method with no error, but nothing is returned?
Some of the methods Serilize, Deserialize, etc. are system methods and does not send these request anywhere.
If the API provider don’t see anything in their logs, perhaps a firewall or something is in the way between K2 and prevents those call from hitting the API server.
From my testing, if the ‘host’ value is unresolvable for example, K2 will still send out the POST request to the specified host in the swagger file, the response to that would be 502 DNS Lookup Failed, but because this Status was not defined in the swagger definition, HttpReponseCode of 0 was returned.
May need Fiddler or some sort of network trace to K2 server to see if the GET/POST request was ever sent and if it was blocked, etc.
I understand that. The HTTPResponseCode property is added at *design* time as soon as the REST Service Instance is created. In other words, it inspects the Swagger file and creates the various Object types and Service Operations. What’s baffling is that I have not been able to determine exactly *when* this property is added.
Correct - I am able to call the SMO method and nothing is returned and when I check with the API provider, like I said, they don’t see any trace of this.
No, K2 is able to successfully execute a simple GET endpoint on the same Swagger so this confirms that authentication, network/firewall, etc. are not the issue
Yes, I understand that Serialize, De-serialize, etc. are internal system methods for string manipulation.
That’s correct - If my host value had a typo, I would get a HTTP Response code of 0
Update: The Swagger had dozens of methods. I need to create a SMO method for only 1 of them. So I manually edited the Swagger to remove all the other methods and now magically the HttpResponseCode property shows up on my Object type definition and I am able to successfully call the POST endpoint and I get back return codes in the 4xx range which has to do with the payload, headers, etc. We know how to handle this.
To summarize - I am still unclear on how the K2 REST broker consumes the Swagger 2.0 file and constructs the various methods and service operations and why certain object types get an REST method attached to them while others do not. As with many things in the K2 ecosystem, the only way to get things to work is by painful trial-and-error. Documentation is poor, support tries their best but not much help, error reporting is obtuse, very disappointing.
Thanks for your help, appreciate it.
@TinTex 1. If the swagger file contains allOf in some methods, does it make the entire swagger file unusable or just the methods that contain allOf?
If POST response is a Json object, you mentioned $ref #/definitions/nobject] is not supported. We can still define the structure?
I believe allOf is supposed to allow you to combine and extend model definitions as per the documentation below:
But since it is currently not supported by the REST Broker, it will likely cause the methods that references allOf or a definition that uses allOf to not behave in a desired manner. This may mean that you may have to create custom definitions instead of using allof for extending model definitions.
You can certainly reference a definition object in a POST response using $ref #/definitions/object].
@TinTex One more question - K2 REST broker created an Object type based on a definition in the Swagger file. This definition doesn't appear to be used by any endpoint/path in the file. We created a smart object based on this object and executed it. It returned a 200 status code. But what exactly did it execute? As mentioned above, I am still unclear on how the K2 REST broker consumes the Swagger 2.0 file and constructs the various methods and service operations and why certain object types get an REST method attached to them while others do not. In other words, if my Swagger file has 10 path keywords, each corresponding to a HTTP method (GET, POST, PUT, etc.), I would expect to see 10 service operations generated by the K2 REST broker but I do not. What determines this? Yes, I did review the documentation on this but it doesn’t match what I am seeing
