Customer Web Service

This page describes is a worked example that can be used on conjunction with the 08 REST Web Services training slides. 

Goal

This provides a set of instructions that a trainer (or trainee) can follow to create a web service to expose Xponent logic as a web service.  With all steps from start to finish documented to create the process, this will give you a repeatable process to build and learn from.

Prerequisites

• 08 REST Web Services slides

You will need to log in to the Journey hub, and have a basic overview of the functionality on the home page.

This picks up from the example on page 21 of the slides.

Ingredients 

You are going to end up with a graph that looks something like this...

So you will need a number of sub graphs along the way.

• createCustomer
• deleteCustomer
• getCustomer

A database 'customer' table e.g. 

CREATE TABLE customer 
  ( 
     custid    INT(11) NOT NULL auto_increment, 
     firstname VARCHAR(100) NOT NULL, 
     lastname  VARCHAR(100) NOT NULL, 
     age       INT(11) DEFAULT NULL, 
     PRIMARY KEY (custid) 
  );

Steps

In order to get this working, first you need a 'createCustomer' sub graph to create a customer, before you can do anything else with the customer records.

Create a new graph, called createCustomer.  

Create a new database connection from the admin tab, called 'MySQL Training' or something you can recognise .  You should have the access creds in your 1Password for Teams vault.

Type - MySQL

User Name, Password, Host Name and Database Name from 1Password,

Port - 3306

This gives the connection, now you can use this for all actions in the adaptor.

Create new Database Adaptor, called insertCustomer.

Select the connection you have just created - MySQL Training.

Set the action to Write.

Add the query 

INSERT INTO customer 
            (firstname, 
             lastname, 
             age) 
VALUES     ( %%firstname%% , 
             %%lastname%% , 
             %%age%% ) 

You can start by adding the values as strings, OR go straight to parameters like the above.

Save this.  You'll now have slots for the parameters.

You'll need to add schema elements for these parameters - you will set these to the values required for the new customer, then pull the values from here to write to the database.

Although we don't like typing, it's probably easiest to just add these elements into the schema.  Add 'customer', then under this, custId, age, firstName and lastName, as well as any other attributes you'd like to store.

Whilst you are editing the schema, it's also worth adding a databaseResponse element for the output.  Under this, add primaryKey and rowsWritten. 
 
The output will give you a rowsWritten value we can evaluate to check the record was written.

Once you have these in place, you can put them into the Parameter slots, and the databaseResponse into the output slot.

Validate this.

Add this into your createCustomer graph.  Give it Return node with an error branch, an error literal.

Set the goto link, and add a 'get' node to get the databaseResponse / rowsWritten value.  Drag out a new node, and set the link to be a conditional, ADVANCED with VAL==1 (if you just use the Basic it tries to evaluate it as a string, not a numeric)

Also give this a goto along with an error branch to return an error.
 

Now, in order to update the customerID in the schema, we need a bit of javascript to get the PK for the record.  

Create new JS called getCustId. Add an argument, pk, then enter the code

return pk[0]

 Add this into you ghost node where VAL==1, 

then put the databaseResponse primaryKey as the PK and the return value as customer/custId 

Drag out a goto link, then set a return node to be a literal 'ok'.

So, now we have the insert node that will write the inbound record to the database.  Now you need to set up the input.  

To do this, you'll need to set up the schema to receive the request info.  Create a new element called request, then add age, custId, firstName and lastName to this 

Now add Set Nodes to the start of the process to set the value of

customer/age to be request/age

customer/lastName to be request/lastName

customer/firstName to be request/firstName

Set the start node to be the first of these... as above.

Now you have a createCustomer graph, we can create the main process.  Create a new graph, called 'customerAPI', and add a new node, and put in your createCustomer graph.

Add a node before this, and replace it as a Get node, that gets the value of the request  

The request will take the form of ?op=createCustomer&firstName=john&lastName=doe&age=50 so you need to create a request element to hold the operation - such as 'op'.  

Drag out a link from the Get to the 'createCustomer' node, and set this to be conditional, ADVANCED and add the following

VAL.op == "createCustomer" && VAL.lastName && VAL.firstName 

This will route all the createCustomer requests this way, and check they have values for firstName and lastName. 

Set some error handling on the Get request to deal with there being no 'op' specified in the request e.g. {"status":"error","code":500,"message":"Internal error"}

Set a goto for where the 'op' is not known e.g. {"status":"error","code":401,"message":"Unknown operation"}

Then set some returns from the createCustomer node, a goto, that picks up any 'not okay' returns from the createCustomer sub graph e.g. {"status":"error","code":500,"message":"Failed to insert to db"}

An error, that picks up errors from this node - same error message as the goto, and an 'equals : ok' that will equal the return value from the createCustomer sub graph...

So, now you can add a listener to the graph.  Click the headphones, set the listener type to API.

Copy the endpoint link to the clipboard, and importantly, set the output for the 'Records Selected' to be /request 

You can now use this to create customers!  Either in a browser, by pasting in the link to the window, with the query string as below...

?op=createCustomer&firstName=john&lastName=doe&age=50

https://api.Xponent.com/api/v1/listener/273e5818596156f4ec194d0ac1354c79?op=createCustomer&firstName=john&lastName=doe&age=50

{"lastName":"doe","age":"50","custId":78,"firstName":"john"}

Or you can use Something like Postman, to build up a suite of test cases you can use to test your API.

DELETE Customer

Now you can add a sub graph to delete customers, by custid.  

You will need a new DB adaptor, set to DELETE, with the code

DELETE FROM customer 
WHERE  custid =%%custid%% 

The custid parameter needs to be /customer/custId

the Output should go into the (schema)/databaseResponse element.

Create a new graph called deleteCustomer.  Ad the delete customer by custId node, drag out a link, and replace this with a Get Node, that will get the value of the databaseResponse (which should be 1). 

Drag a conditional link out from here, with an Advanced condition VAL == 1

Add a return node with an 'ok' type response.

You should then add a SET node at the front of this, to get the custId to delete to be the custId from the request 

Add some error handling, and you should have a deleteCustomer graph that looks like the image above.

Add this into the Customer API graph, and set the link from the Get request to be 

VAL.op == "deleteCustomer" && VAL.custId

Test using ?op=deleteCustomer&custId=10

GET CUSTOMER

This will work in a very similar way.   You need a DB adaptor that has a READ action, with the following code...

select * from customer where custId = %%custId%%

Parameters are set to be (schema)/customer/custId, and record selected to output to (schema)/customer

The set node should set the value of cust ID to be the request custid

Test using 

?op=getCustomer&custId=**