API Listener

Standard API Listener 

The Standard API Listener will accept data sent in a web service GET or POST request and will return the value from the Return node on the graph. 

The web service endpoint for the standard API listener is shown as the Endpoint (URL masked below) and is immediately accessible as soon as the graph runs. Any GET or POST data is put into the Schema location selected by the Output location. Any query parameters and the HTTP headers are automatically available in the _kw schema location. Any POSTed data is put into the Schema location selected by the Output location. 

The standard listener creates micro web services that external systems can use easily. 

Different design patterns can be used with the Xponent Graph API to deliver services: 

1. Each graph is its own micro-service, handling one operation 
2. A single graph can be the entry point for multiple operations, using an "op" query parameter and then subgraphs handling the different operations
3. For those with strictest needs, Same as 2, but using the JSON-RPC style, which defines the structure of the JSON messages 

Following on from the second option above, these recommendations should be kept in mind: 

• Think of this API endpoint as offering a number of operations - each of which is a procedure or function that takes a set of arguments as input and (optionally) returns some value 
• Have an 'op' query parameter that specifies the operation to be performed
• Pass arguments that modify the way that the operation functions as additional query parameters (think of these as parameters to your function) 
• Pass arguments on which the function operates either as query parameters (GET) or in the body (POST) 
• Use POST when the arguments contain sensitive information (user-identifiable information) or have characters that may be problematic on a query string (email address) 

The API requires the Content-Type header field to be set to "application/json" when performing a POST operation. This needs to be explicitly stated in the POST; otherwise, it will use the client's default setting.

For Example:

In Curl, the default Content-Type header is "application/x-www-form-urlencoded".

In Postman, it is "text/plain;charset=UTF-8".

For instance, if you were using Curl, the correct command for calling the endpoint would look something like this:

curl -H "Content-Type: application/json" -X POST -d '{"body":"this is my body"}' https://api.kitewheel.com/api/v1/listener/{listenerID}

If the content type is not specified, you will receive one of the following errors for a deployed graph:

{"message":"undefined is not a function","error":{}}

And this for a graph in visual testing:

{"message":"req.msgBody.hasOwnProperty is not a function","error":{}}

Sample Web Service End Point 

For Example: an endpoint that supports CRUD (Create Read Update and Delete) operations on a 'profile' can be represented as follows: 

A decision tree can be used to check the correct operation and method combination.

This can be used in a graph with this kind of structure - where each ghost node would be replaced by the specific graph that implements the required operation.