API Listener

Standard API Listener 

The standard 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 end point for the standard API listener is shown as the Endpoint (URL masked below) and is immediately accessible as soon as the graph is running. 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 makes it easy to create micro web services that can be used by external systems. 

The design pattern is to use a Remote Procedure Call (RPC) approach rather than a RESTful design. This means that the two methods GET and POST should be used for all operations. There are different design patterns that can be used with the Xponent Graph API to deliver services: 

1. Each graph is its own micro-service, handling 1 operation 
2. A single graph can be the entry point for multiple operations, using an "op" query parameter and then subgraphs handing 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 end point 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 contain 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 e.g. 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 error 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 

As an example an end point 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 of the ghost nodes would be replaced by the specific graph that implements the operation required.